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RADIO AND TELEVISION INTERFERENCE 



The equipment described In this manual generates and uses radio 
frequency energy. If it 1b not Installed and used properly, that is 
in strict accordance with our Instruction*, it may cause interference 
to radio and television reception. 

This equipment has been tested and complies with the limits for a 
Class B computing device in accordance with the specifications In 
Subpart J of Port 15 of FCC rules. These rules are designed tn 
provide reasonable protection against such interference In a 
residential installation. However, there is no guarantee that the 

interference will not occur in a particular installation. 

You can determine whether your computer is causing interference by 
turning it off. If the interference stops. It was probably caused by 
the computer. If your computer does cause interference to radio or 
television reception, you can try to correct the interference by 
using one or more of the following measures: 

- Turn the TV or radio antenna until the interference stops. 

• Move the computer to one side or the other of the TV or radio. 

- Move the computer farther away from the TV or radio* 

- Plug the computer into an outlet that is on a different circuit 

from the TV or radio. (That is, make certain the computer and the TV 
or radio are on circuits controlled by different circuit breakers or 
fuses.) 

If necessary, you should consult your dealer or an experienced 

radio/television technician for additional suggestions* You may find 

the following booklet prepared by the Federal Communications 
Commission helpful: 

"How to Identify and Resolve Radio-TV Interference Problems" 

This booklet is available from the U.S. Government Printing Office, 
Washington, DC 20402, Stock number . 



PREFACE 



This manual has two primary functions 

use the DOS <Dlsk Operating System); 

i-xamplcs to accompany explanations of 

The second Function of the manual la 

DOS- The Appendices, Quick Reference 
with this function in mind. 



• The first is to teach you how to 
the Chapters of the manual use 
how the various DOS commands work. 

to serve as a reference guide to 
Card* and the Indices were planned 



To uae an Apple Disk II, you need an Apple II computer with at least 16K 
or memory — but 32K Is recommended, since the 16K system allows littla 

memory space to store programs. In fact, the HDFFIH program and the FID 
program on your System Master Diskette need 32K of memory to run. For 
using Apple Disk II with Applesoft on casette tape or on diskette, your 
computer must have at least 32K of memory- 

The Apple Disk II is a "floppy" disk unit which allows you to store and 
retrieve information much more quickly and conveniently than you can 

Hmin^Kl^* 1 ^ !^ 110 " \* " ore ? *nd retrieved from a "diskette", a 
amnll {about 5-inch diameter) specially coated plastic disk which is 

permanently sealed in a square plastic case. 

One of the most important advantages to using Disk II is that 
information is stored and retrieved by a name under which it is filed. 

A program that catalogs phone numbers might be saved with an instruction 

such as 

SAVE PHONE NUMBERS 

and retrieved with an equally simple command. The name PHONE RUHSEBS 
under which the program Is filed is a file name . 

The programs that automatically keep track of files, save and retrieve 
information, and do a multitude of other housekeeping tasks are called 
the Disk Operating System , usually shortened to "DOS". Some people say 
"doss" and others say "dee oh ess". Learning to use DOS and the dlak 
consists of learning a few special DOS commands described in this 
manual. These commands can be used as extensions to either Applesoft or 
Integer BASIC or machine language programs. 

At some places you'll see the symbol 

s 

preceding a paragraph. This symbol indicates an unusual feature to which 

you should be alert. 

The symbol 

precedes paragraphs describing situations from which BASIC may be unable 
to recover. You will lose your program, probably have to re-start DOS, 
and may have to re-start BASIC. 



*" NOTE *** 



This manual applies to vert ions of DOS that 
operate In 16 sectors. That ia, DOS vcralon 3-3 
and subsequent, If you have an earlier version 
of DOS, It will operate in 13 sectors- To update 
your 13 sector DOS to 16 sectors* change the 
proms on your disk controller card as instructed 

In Appendix H t and use the HUFFIK program to 

move your data to 16 sector diskettes. To boot 

a 13 sector diskette on yosr 16 sector system, 

use the BASICS Diskette that cooes with your Disk 11 
or your Disk IT Update kit. 

Under some circumstances, a diskette converted 
by MUFFIN may turn out to be un-runnable* This 
happens when the program on the diskette expects 
to find Instructions at specific locations on the 
diskette itself- Host programs don't fit that 
category, but a few do. Reocmber, KUFFlNing 
a diskette won't hann your 13 sector diskette, 
and you can always boot 13 sector diskettes 

using BASICS. 
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TION AND HANDLING 



Unpacking 
Connecting the 
Installing the Controller 
limtilltftft Multiple Disk Drives 
Care of the Disk II and Disaelt** 
laftvrticft sod tow/ Lug Diskettes 



UNPACKING 



Your Disk II system consists of several Items. Among these you will find: 

1) The disk drive (the train box). 

2) A printed-clrcuit card (the controller card) 
that plugs into the Apple IX. 

3) A flat ribbon cable, already fastened 
to the disk drive, for connecting 

the disk drive to the controller card. 

4) A "SYSTEM MASTER" diskette. 

5) A "BASICS" diskette. 

6) This manual. 

If you have purchased a drive only (for example t as a second drive for your 
controller card) your system will not include all of the above Items- 

Save the packing material in case you wish to transport your disk — or in 
the unlikely event you must return It to your dealer or to the factory for 
service. 

*** Special Note *** 

Before connecting or disconnecting 
ANYTHING 
on the Disk II or Apple II 

TURN OFF THE POWER. 
This is a must. 

CONNECTING THE CABLE 

In use, the disk drive will be connected to the controller card by the 
flat* ribbon-like cable- One end of this ribbon cable is already fastened 
to the disk drive- If this is your first disk drive, the connector at the 
end of the ribbon cable from this drive should be attached to the upper 

set of pins on the controller card. This set of controller card pins is 
labelled "DRIVE 1". 

*** Caution *** 

If the cable from the disk drive to the controller card is not plugged into 
the controller card correctly, considerable physical damage can be done to 
the disk drive unit and its electronics. To assure correct assembly, be 
sure to plug the ribbon cable into the controller card before installing the 
controller card into the computer* Two installation tips follow- First, 

don't jam the cable between the connector and the controller card. When the 

cable is plugged into the controller card correctly* the cable should exit 
from its connector on the side of the connector that is away from the 
controller card, as shown in the photograph. Second, make sure that all the 
pins of the controller card's connector go into the matching holes in the 
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ribbon ruble's connector. By making the connection before installing the 

rard, you can actually see that alt the pins are going into the holes 
correct ly* 





n Connecting the Cable to the Controller 



If you are installing a second disk drive, you should connect the ribbon 

cable from the second drive to the lower set of pins on your controller* 
This set of pins is labeled "DRIVE 2". Take the same care attaching this 

connector as you did with the first. 

If you are updating an earlier version of DOS to sixteen sectors, you will 
need to change two proms on your existing controller card. Read Appendix H 
to find out how to do this. 

INSTALLING THE CONTROLLER 

To install the Disk II controller card, which you have already connected to 

the disk drive via the ribbon cable, you will simply plug the controller 
card into a socket inside the Apple II, as follows: 

1. Turn off the power switch at the back of the Apple II. This is 
important to prevent damage to the computer. If the power is on, removal 
or Insertion of any card could cause permanent damage to both the card and 
the Apple II. 

2- Remove the cover from the Apple II. This is done by pulling up on the 
rover at the rear edge (the edge farthest from the keyboard) until the two 
corner fasteners pop apart- Do not continue to lift the rear edge, but 

slid* the cover backward until it comes free. 

3- Inside the Apple II, across the rear of the circuit board, there is a 
row of eight long, narrow sockets called "slots". The leftmost one 
(looking at the computer from the keyboard end) is slot 00, and the 
rightmost one ts slot (7. Locate slot #6, one socket to the left of the 
rightmost socket- The controller card may be placed In any slot except 
sloe fffl, the leftmost. However, AppJe's standard location for the disk 
controller card t* slot #6, and most Apple software (and this manual) is 
written with that location in mind. 
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4. BE SURE THE POWER IS OFF BEFORE YOU INSERT OR REMOVE ANY CARD FROM THE 
COMPUTER. Insert the "fingers" portion of the controller Into slot #6- 
The "fingers" portion will enter the socket with some friction and will 
then seat find/. Since the fingers make electrical contact, it is a good 
idea to keep your fingers from touching thera. Before installation, you 
nay wish to use rubbing alcohol to, clean the fingers on the board (and, 
optionally, your own fingers if you're so inclined). 




Inserting the Controller Card 



5- Adjust the ribbon cable so it lays flat and passes over one of the 
areas between the vertical openings in the back of the Apple II case* as 
shown In the drawing. When the lid Is installed it will clamp down the 
cable and act as a strain relief. 




Cable Placement 



6. Replace the cover of the Apple II; remember to start by sliding the 
front edge of the cover into place. Press down on the two rear corners 
until they pop into place. 

7. The Disk II controller is installed, and the Apple II uy now be 
turned on. Place the disk drive in a convenient location, usually 
alongside of or on top of your Apple II- 
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INSTALLING MULTIPLE DISK DRIVES 

Kach controller card can be used with two disk drives, one attached to the 
upper net of pins, labeled "DRIVE 1", and the second attached to the lower 
■•t of pins, labeled "DRIVE 2". Your first disk drive should be attached to 
tin- DRIVE 1 pins and the second to DRIVE 2 pins on the card in slot #6. The 
third and fourth drives should be attached to the DRIVE 1 and DRIVE 2 pins, 
H rt-Npectively, on a cord in slot #5, th« fifth and sixth drives attach to the 

DRIVE 1 and DRIVE 2 pins on a card In slot #4, and so on. 

r ^ 



If you have multiple drives. It is a good Idea to label the front of each 
drive with its slot and drive number since your programs will refer to the 
disks by those nuofcers. 



P S| CARE OF THE DISK II AND DISKETTES 

_ The Disk II drive, unlike the Apple II, Is a mechanical device, with motors 

^ md moving parts. Therefore it is somewhat more delicate than the 

computer. Rough handling, such as dropping the drive, or having things 
j£ 3 drop on it, can cause it to malfunction. The drive should not be placed 

beside or on a TV set, since the strong magnetic fields put out by TVs may 
cause damage to the magnetic properties of the drive. If in doubt, locate 
(i> 5J disk drives at least 2 feet from any TV set* 



Bach diskette Is a small (about 5-inch diameter) plastic disk coated so 

that information may be stored on and erased from its surface* The 

coating is similar to the magnetic coating on recording tape. The 

Wfl 1 3 diskette is permanently sealed in a square black plastic cover which 

protects it, helps keep It clean and allows it to spin freely. This 

package is never opened. 



The term "floppy" cornea from the fact that the diskette Is flexible. Older 
computer information storage devices that worked on similar principles 
used rigid disks. While the diskette (and Ita plastic cover) are somewhat 
flexible, actually bending the diskette can damage it. The diskette cover 
contains both lubricants and cleaning agents to extend trouble free 
operation treat covers with respect- 

Never let anything touch the brown or gray surface of the diskette itself. 
Handle the diskette by the black plastic cover only. When a diskette Is 
not in use, keep It in the paper pocket that it came in. These pockets 

are treated to minimize static build-up which attracts dust. It is best 
to store diskettes vertically when they are not in use. Vinyl notebooks 
especially made for this purpose are convenient. 

Diskettes hold a tremendous amount of information: a single diskette can 

hold over 1.146,000 bits of information. An individual bit of 

inf o nut Ion i therefore, occupies a very small portion of the diskette. An 

invisible scratch on the surface of the diskette, or even a fingerprint, 
can cause errors. Do not place diskettes on dirty or greasy surfaces; do 

not let them collect dust. 
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To write on a diskette label, use a FELT TIP pen. Do not press hard. It 
is best not to write on a label attached to a diskette, but to write on 
the separate label , t hen attach it to the diskette. 

Keep diskettes away from magnetic fields. This means to keep then away 
from electric motors and magnets; they should not be placed on top of 
electronic devices such as television sets* They may be temporarily laid 
on the Apple II or the Disk IT. 

Diskettes arc sensitive to extremes of temperature. Keep diskettes out of 
the sun, and away from other sources of heat that can cause then to warp 
and/or lose data. On hot days, car trunks (or dashboards) can be diskette 
killers. Diskettes operate satisfactorily up to 125 degrees Fahrenheit 
(51.7 Celsius), which is not very hot. The first evidence of heat damage 
is a warped or bent black plastic cover. 

With reasonable care a diskette will give you an average life of 60 hours 
— which is a lot, when you consider the few seconds it takes to LOAD most 
programs. With just a little bit of carelessness, a diskette may give you 
no service at all. 




INSERTING AND REMOVING DISKETTES 

Using a disk drive is far quicker and easier than using a cassette 
recorder, however some care is necessary to protect the diskettes* The 
drive itself must also bo handled with some care. The drive door is 
opened by pulling outward on its bottom edge- The diskette is then 
slipped Into the slot with the label upwards , as shown In the 
photograph. The edge of the diskette with the oval cutout in the 
diskette's square plastic cover ihould enter the drive first . The edge 
of the diskette with the label should enter the drive last. 



A Good 
RULE OF THUMB 

Hold a diskette with your right thumb over the label: 
that pretty much insures the correct orientation 
when you put the diskette in the drive. 
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Inserting a Diskette 



Push the diskette gently until the diskette is entirely into the drive. 
Do not bend the diskette! If it is pushed in too hard, the diskette can 
be permanently damaged. Close the drive door by pushing it down again. 
The two metal fingers (which can be seen inside the slot when the drive 
door is closed) should ju«t clear the diskette as the door closes. 

A diskette is removed by opening the drive door and pulling the diskette 
carefully out of the drive. The act of opening the disk drive door lifts 
the "head 11 off the disk. IE you plan to leave an unused diskette in a 
drive for several hours* it's a good idea to open the door so the head 
won't rest on the diskette. 




NEVES remove a diskette while the drive's "IN USE" light is on. This may 
permanently damage the diskette, and Is almost sure to destroy the 
Information on it. In such a case, the diskette can usually be re-used, 
but you won't be able to recover the lost information* 
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BACKGROUND 

Learning to use the disk and its operating systea consists of learning a 
few special instructions, severs] of which are straightforward extension** 
of familiar BASIC instructions* This manual assumes that you're familiar 
with the Apple II, and feel comfortable writing simple BASIC program**. 

To loarn how to use the Apple 11 and Integer BASIC, consult the Apple II riC j [ (|! 

8*S1 C Pr oRramplng Manual (Apple Product #A2L0M5X). To learn how to use 
Applesoft BASIC, consult the Applesoft II BASIC Programming Reference 
Manual (Apple Product (A*!L000b). The Applesoft manual assumes you're 
already familiar with the Apple II and simple BASIC programming. If 
you're not familiar with cither manual, we will wait here while you learn 
about the Apple 11, before going on to learn about DOS. 

* 
* 



Even though DOS commands loo k like BASIC commands, they do not always 
follow the same rules. For example, Multiple DOS commands can not be put 
on one line, separated by commas* The SYNTAX ERROR message results. 



SPECIAL KEYS 



HI* 



■rjUi 



Throughout the manual arc listings of programs that illustrate how to use 
DOS. Most of these programs ore in Applesoft; a few are in integer BASIC. 

Sometimes the changes needed to convert an Applesoft program to Integer 
BASIC are mentioned; other times, they are not* Consult Appendix M in the 
Applesoft manual for details on the differences between programs written BLLii "«9| 

in Integer BASIC and Applesoft BASIC* 



A little bit of hands-on experience is worth a lot of reading* Once your 
disk drive Is hooked up and the computer is turned on, follow each of 
these descriptions by actually trying out the procedures on your Apple II. 



Put the Apple II into BASIC — either Integer BASIC or Applesoft. Place 
the System Master diskette into the drive. The diskette should be BETjj 
labelled 004-0002-XX. The last two digits are indicated by X's, since it 
doesn't matter what they are. If you have more than one drive* use Drive 
I* This section of the manual only deals with one drive and assumes that 
you've followed the standard conventions, putting the controller into slot 
#6. 
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With the disk drive attached, and the diskette in the drive, and the disk 
drive door closed, you will find that the Apple II performs }ust as it did 
without the disk* Nothing is changed. It is os if the disk drive were 

not there* And, as far as the Apple II is concerned, the disk drive is 1 
not connected yet: a special coosand must be given to inform the computer P^-'-^S 
that the disk drive and the new DOS instructions are available. 
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Sometimes this manual uses the curly brackets { and ) to enclose the SE^ •J 

names of special keys which you are supposed to press on the Apple II 

keyboard. — . 

m" 3 

« i q 



(RETURN ) means you should press the key narked "RETURN". Press the RETURN 
kry after each Instruction. 



(RK,SET> means press the key narked "RESET". If you have an Autostart ROM, 
•pres. of the RESET toy will cause the Apple to beep and display a prompt 
character. With the old ROM, a press of the RESET key will put you Into 
the MONITOR program, which uses * as Its prompt character. 

(ESC) Beans press the key marked "ESC". "ESC originally meant "escape", 
hut nowadays has other uses. 

(CTRL J is a bit different. It means you should press the key marked "CTRL" 
(which stands for control) and continue holding it down while you type 
another key. For example, {CTRL)C means type the "C" key while you are 
Holding down the CTRL key. Sometimes use of the control key Is indicated 
In another way: CTRL-C and {CTRL)C both mean the same thing. 

*** NOTE *** 

Characters typed while holding down the CTRL key 
do not appear on the screen. 

BOOTING DOS 



The process of odding the DOS commands to the BASIC in your Apple II is 
culled booting the disk. The disk may be booted from Integer BASIC, from 
Applesoft or from the Monitor. There are various ways you can use to boot 
DOS. Prom Integer BASIC or Applesoft, the PRIs and IHfs commands (see 
your Applesoft manual) may be used. From the Monitor, "control commands" 

same DOS: It doesn t matter how you got there. 

In the examples below, tha lower-case letter s stands for the number of the 
Apple U slot in which your dUk controller card Is located. The standard 
location for the controller card is slot #o (see Chapter 1, Installing the 
Controller). After any of the following commands, you must press the 
RETURN key - 

From Integer BASIC (whose prompt character is > ) 
you can use either of these commands to boot the disk: 

You type: PR#a Example: PR#6 

«: »Cs Example: IN#6 

From Applesoft (whose prompt character is 1 ) 

you can use either of these commands to boot the disk: 

You type: PR# 8 Example: PR*6 

or: Example: IN#6 

From the Monitor (whose prompt character Is * ), 
you can use either of these commands to boot the disk! 

You type: Ctf#G Example: C60flC 

or: s(CTRL>P Example: 6{CTRL>P 
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In the rest of this annual, when you are to re-start the DOS in this manner 

we will simply say: "boot the DOS" or "boot the disk". Both expressions 
(very popular among computer users) mean the same thing. "Boot" is short 
for the word "bootstrap" and the term Is from the expression "to pull 
oneself up by one's bootstraps". In any case* it does not mean to kick the 
disk, even if you do feel in such a mood from time to time. 

Now try booting DOS from your System Haster diskette. Start by putting 
your Apple II in BASIC — either Integer BASIC or Applesoft will do. Be 

sure the diskette is properly inserted. Next type 
PR#6 

and press the RETURN key as usual. From now on, it will be assumed that 
you will press the RETURN key after each instruction. 

Once you press the RETURN key, the red "IN USE" light will come on, the 
disk will make whirring and clacking noises (don't be alarmed — it's not 
getting ready to fly away) and in less than 10 seconds, a message will 
appear. The message should be similar to the following: 

If you now try to use BASIC, you will find that most commands still operate 
normally and, aside from the message suddenly appearing, the Apple II seems 
unchanged. What has happened is this: a few new commands have been 
introduced, and a few old ones have new capabilities. Two changes have been 
made that are not obvious, however: 

1) The HIMEM pointer to the highest memory location you may use 
has been reset to accomodate the DOS program. 

2) Your Apple II may have lost some of its high-resolution 
graphics capabilities, depending on the amount of memory 

In your computer. 

** Versions of DOS that use 13 sectors can't be booted when the system 
expects 16 sector diskettes. (The diskette spins and hiccups, but nothing 

comes out-) To run a 13 sector diskette, update it to 16 sectors with the 
MUFFIN program. You can also use the BASICS diskette to boot 13 sector 

diskettes on your sixteen sector system. See Appendix I to learn how. 

IF BOOTING DOESN7 WORK 

If you can't successfully boot your System Master diskette, re-read the 
manual carefully — that cures 90Z of all problems. 

This isn't likely, but If your unit was shipped in a Sherman tank or some 

such, the connectors inside the disk drive may have worked a bit loose. If 
you are at all squeamish about handling the insides of your drive, your 
dealer will be glad to check it out. 

If you enjoy getting your fingers into the works, you can turn the computer 
off, and disconnect the drive from the controller. Loosening the four 

screws on the bottom of the drive allows the mechanism to slip forward out 
of the case. Tighten the connectors by pushing them gently onto the 
circuit boards. 



12 



* 1 



Re-assemble the unit and It will probably now work. If this first aid 
doesn't work, see your dealer. Don't make any adjustments. 

INITIALIZING NEW DISKETTES 

The System Master that comes with this manual is a very special diskette: 

it contains programs that allow you to copy an entire diskette, update any 
diskette that has an earlier version of DOS, and more. Programs that 

dtiOMt rate various capabilities of DOS are also included on the diskette 
and discussed in the manual* 

Take the System Haster diskette from the drive, and replace it with the 

other blank diskette supplied with your drive. How try an experiment. 

Cvt BASIC going, then type 
PR 06 

and watch what happens. The red IN USE light cones on, and the disk drive 

makes a few clackety noises, then it Just keeps whirring softly and quietly 
and it doesn't stop. You'll have to press the RESET key to stop it 

(normally, this is a BAD Idea, but these circumstances aren't normal). It's 
a good Idea to open the disk drive door before pressing the RESET key, since 
that lifts the head of the disk drive off the surface of the diskette. 

What happened was this: your Apple II went on a fruitless unending search 
for information on a blank diskette (on a clear disk you can seek 
forever*-*)* When a new diskette is manufactured, it contains no 
information at all, like a blank tape purchased for a tape recorder. To 
operate in the computer, there must be special Information placed on the 

diskette: the diskette must be initialized. 

If you've been keeping up with the hands-on part of the example, your blank 
diskette is in the drive and you Just pressed the RESET key. Now take out 

the blank diskette, replace it by the System Master diskette, and close 
the door of the drive. Get the computer into BASIC and type 
PR #6 

again. You should again get the message you got before when you booted- 
Once more the DOS commands have been added to BASIC. 

The 1NIT command can be used to IHITialize a "slave" diskette. Slave 

diskettes are memory-size dependent; the size of the system which 

initializes the diskette determines the size of the system which can use 

the diskette. If a slave diskette Is created on a 32K system, then it can 
only be used on a system with 32K or more memory. On larger systems, only 

32K of memory will be used. After lNITializing a slave diskette, you can 
use the HASTER CREATE program (see Chapter 5) to tranform your slave 
diskette into a "master" diskette whose DOS is self-relocating so that 
memory Is used efficiently. The MUFFIN program will allow you to transfer 

the contents of your 13 sector diskettes to 16 sector diskettes* 

The INIT command requires the use of a BASIC program called the "greeting" 
program since ft greets you: each time you boot the diskette the program 
will be run automatically* The greeting program is commonly naaied "HELl-O" 
hut you could call it "BONJOUR" or "BUENOS THAS" or whatever you like. It 
helps keep life simple to use a standard name for greeting programs as you 
INITlalize diskettes. 
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Here's a atep~by-etep guide to INITialixlog a slave diskette. We assume 
DOS lfl already booted as described above* 

1) Remove the System Master from your disk drive and replace It vith 
a blank diskette- 

2) Type NEW* then type a greeting program. Here Is a simple sample of a 
greeting program: 

™> *!fr! bJflfcEUHCi-1 WjaSHr 

- ' ■ 

You should supply your own name , system size* the current 
date and other Intonation to help you quickly and easily 
determine the diskette's history and slave /master status. 
You may BUN the program to ace If It does what you expect. 

3) Once the program is satisfactory, type this Instruction: 
IN IT HELLO 

When you press the RETURN hey, the diskette will spin for nearly 
a minute, making clacks and little whiapery noises every 
now and then. The appropriate prompt character (e.g., ] for 

Applesoft) will be displayed when INITlalixatlon Is complete. 

4) Mien the disk quiets down and the IN USE light goes off, 
remove the diskette and label it* The label should aay 
something like 

32K SLAVE DISKETTE CREATED 8 AUGUST 1980 

so that Just by looking at it you know it isn't blank. 

Put aside the System Master diskette supplied by Apple Computer. Put it 

where it won't be damaged by heat f physical stress (kids? dogs?) or 

magnetic objects. And where it won't get lost. It should be treated 
especially carefully, since it contains many useful programs. 

Once a diskette haa been INITiallzed, it will be referred to as s slave 
diskette. To label your slave diskette, you had to take it out of the 
drive. Put it back in and try booting it: the message in your PRINT 
statements should appear. If you followed the model given above, the 
screen should say: 

W wis On 6 MAtS 1 * 

Since the once-blank diskette now can boot, you know that it has been 

INITiallzed correctly. From this point on you will use the newly 
INITlallted slave diskette for experimentation. You cannot do some of the 
procedures to be demonstrated below on the System Master, because the 

diskette ia "write protected", as discussed in Chapter 4. 

If you have purchased additional blank diskettes. It would be a good idea 
to INITialiee a few of them now. 



LOAD-IMG AND SAVE-MO WITH DOS 

Boot the aywtem with your Initialized diskette. Type 
NEW 

to make sure no programs are in memory. This will erase your greeting 
program (which Is LOADed and RUN when you boot DOS) fro* memory (but not 
f mm r I-, diskette). 

Nnw type this simple program: 

lfc* FOR I * 1 Tt) 10 
2& NEXT J 



RUN it once or twice to make sure that it works as you expect. In 
Applesoft, when the program is RUN you'll see this: 

S S 3 

4 3 6 

r 9 9 

For reference purposes, call this program ONE TO TEN, since it counts from 
one to ten. To store this program on the diskette, type the instruction 
SAVE ONE TO TEN 

When you complete the command by pressing the RETURN key t the disk will 
whirr for a few seconds, and the program will be saved. 

If you had typed 
SAVE 

without any name, the program would have been saved on cassette tape, as 
usual (assuming you had operated the tape recorder as described in the 
BASIC Programming Manual!. 

To prove that the program has been SAVEd on diskette, do the following. 

Elrat, type 

LIST 

then 

RUN 

to see the program is still in memory and still operates properly. This 
demonstrates that using DOS to SAVE a program on a diskette doesn't affect 
the program in any way. 

Now type 
NEW 
then 
LIST 

There will be no program left at all ~ it disappeared when you typed NEW. 
To really make sure the program is dead, turn off the computer. You can 
even take the diskette out and put it (gently) back in again. Turn the 
computer hack on again, get into BASIC and boot the DOS. Type NEW (which 
erases the HELLO program), and then LIST. Nothing there? Right* 
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Now type 

LOAD ONE TO TEN 

and the disk will whirr Cor about two second*- LIST the program: It is 
revived. RUN it, and you will find it in perfect health* That is all there 
is to SAVElng and LOADing programs from disk: it's Just like using the 
cassette tape except that a file name Is used, and It's faster* 

CATALOG 

You stored the program ONE TO TEN on your diskette. Actually* you had 
already stored another program- To see what programs are stored on a 

given disk, type the command 
CATALOG 

and a List of all the programs on the diskette will appear* Right now your 
diskette's catalog should look like this, if your programs were written in 
Integer BASICi 

I #*2 HELLO 

I OWE TO It* 

The letter "I" In the left column means that the programs are In Integer 
BASIC; before names of Applesoft programs you'll see an **A"# Besides BASIC 
program files* there arc also other kinds of files that can be stored* and 
they will be explained in Chapters fi through 9* The numbers after the 

file-type letter represent the length of the stored program. In this 

case, 002 diskette "sectors" were required to store the program- Each 
diskette sector can store up to 256 bytes of information. The shortest 

possible file* an empty text file (see Chapter 6), requires (101 sector to 
record certain "housekeeping" information* In all, a diskette can store 
496 sectors of programs and other files. Lastly* each entry in the 
catalog contains the name of the program. See Appendl* C for details on 
how Information is stored on the diskettes* 

When a file exceeds 255 sectors* the length reported for that file by 
CATALOG starts over again at 000- 

X 

There Is no way to tell from looking at the CATALOG which program is the 
greeting program. So It helps If you always give the same name to your 
greeting program. 

Sometimes you'll have more programs on a diskette than will fit on the TV 
screen at one time. CATALOG will cause the first 18 programs to be 
listed. When you're ready to see the other programs on the diskette, 
press any key except the RESET key* CTRL key or the SHIFT keys. 

WHAT'S IN A NAME? 

Flic nawes nust he from 1 to 30 characters in length; DOS will truncate 
longer file names to 30 characters. A file name must begin with a letter- 
Any typeable character except the comma ( , ) may appear In the name. 
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Here are some legal file names: 



BOKHAMBULISTlCS 

ONE TO TEN 
HIRfcS 34 

THE QUALITY OK MERCY: UNSTRAINED 

Here a few names that will not work (and reasons why): 

I TO 10 (begins with a digit) 

HI THERE , BARK (contains a comma) 

INEPT EXCESS VERBIAGE DISQUALIFIES NAMES (will be cut to 3* characters) 

Although the name of the laat file will be cut to 30 characters when 
displayed by CATALOG t you can, if your fingers can take It, type the 
entire name when LOADing or RUNning, and all will work correctly. 

Every line in the catalog represents a "file". The BASIC program you 
stored Is an example of a file. The rules given here for file names also 
apply to the names of programs* 



If a control character is accidentally (or even purposefully) typed into a 
name, that character will not appear on the screen when you get a catalog. 

For example. If you type (CTKL)T instead of plain "T" In the name 
"AflATHA", the catalog Hating would appear to be 
AC AHA 

However, if you tried to LOAD that file by typing 
IX>AD AGAHA 

the computer would reply 
PILE NOT FOUND 

even though the name you typed seemed to be Identical to the name in the 
catalog. So be careful: don't inadvertently put control characters in 
file names. (Although, heh heh. It's a clever way to keep you out of my 
bank records If all files have secret control characters embedded in 
thorn.,.) The File Names section of Appendix F contains tips on how to 
find out what control characters are imbedded in file names. 



RBMAME-ING FILES 

For one reason or another, you'll occasionally want to change the name of 
a file. Suppose you get tired of typing the file name ONE TO TEN and 
decide to call the file COUNT* Just type 
RENAME ONE TO TEN, COUNT 

and after a moment of whirring you'll again see the BASIC prompt 

character* Now type 

f:ATAI-OC 

to verify chat all went as planned* 



Tlio RKNAHE command does not check to see whether the new name you're 
ualng already exists or not, so It's entirely possible that you can RENAME 
until all files on a diskette have the same name*. -a most undesirable and 
confuting situation that is best avoided. 
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DELETE-ING FILES 



It is easy to remove files from the diskette. Type 
CATALOG 

again to see the two files that are on your diskette* How type 
LOAD COUNT 

(assuming you changed the file name as shown above) to get that program 
into memory. Delete this program from the diskette by the instruction 
DELETE COUNT 

and test that your deletion has worked by typing 
CATALOG 

Only the greeting program — probably called HELLO — is left. Since the 
program COUNT is in armory {that's why you LOADed it), you can place it 
back onto the diskette with the familiar command 
SAVE COUNT 

Take a look at the catalog to sec that the progran is again on the 
diskette* 

If you try to DELETE a file that's not on the diskette, you'll receive the 

FILE NOT FOUIID 
message. 



RECOVERING FROM ACCIDENTAL RESETS 

Suppose you're without the DOS in either Integer BASIC or Applesoft. {If 
Applesoft is In firmware, w assume the switch on the card is set for 
Applesoft). If you accidentally strike the RESET key, you can recover with 
your program intact by using CTRL-C. The DOS also has recovery procedures 
that vill usually preserve your program and data. 

If you are working with an old Monitor ROM and have already booted DOS, and 
then press RESET, you get the Monitor ( * ) prompt. To return to DOS and 
the BASIC you left, type 
3D0C 

Remember that's a zero, not the letter 0, between the totters D and G* 

If recovery to DOS does not work, and the program still LISTS, all is not 
lost: save the program on tape (you did remember to keep your tape drive 
for just such an emergency, didn't you?)* Then at your leisure you can 
boot DOS, LOAD the program from tape, and SAVE it on a diskette. 



If you accidentally (or intentionally) hit the RESET key while the disk's 
red "IN USE" light is on, the information on your diskette may be 
clobbered. Problems are most likely to occur if this happens when you're 
putting information onto the diskette using a SAVE, BSAVF, or WRITE 
command* In the event that it is clobbered, you probably won't be able to 
recover your programs from the diskette. If nothing else works, you can 
re-initlnll2e the diskette and use it again, but IHITinlifcing destroys all 

the files on the diskette* 
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If your IN USE light stays on for several minutes but you don't hear the 
usual disk sounds, your system may be "hung". Pressing RESET may be the 
nnly way to turn off the light so you can restart the system. 

A diskette can be partially clobbered, so that it vill not boot. However, 
in such a circumstance, you can sometimes boot another diskette, then LOAD 

programs from the partially clobbered diskette and save them on an un- 
d a maged diskette. Or use the FID program to copy Individual files or 
programs* 
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DRIVE, SLOT AND VOLUME OPTIONS 

Host DOS commands allow you to specify a number of options, such as which 
disk drive you arc using, which slot contains the disk controller for that 
drive, and a "volume number" for the disk. 

The disk drive option allows you to operate with more than one drive. 
Each controller has the ability to control either one or two disk drives. 
Normally, Instructions refer to drive 1. This is the default drive 
selection: if you don't specify a drive, drive 1 will be used. If you 
wish to specify drive 2, you use the notation D2 separated from the file 
name or other disk options by a comma. For example, to Initialize a 
diskette in drive 2, you could use the Instruction 
INlT HELLO, D2 

After drive 2 has been specified, all further disk commands refer to 
drive 2 until drive I is again specified. Drive 2 is now the default 
drive. After the above INlTlalixation, the command 
CATALOG 

will list the files stored an the diskette io drive 2. To specify drive 
1* y°u us* the notation Dl separated from the file name by a comma. For 
example, 
CATALOG, Dl 

will show you the contents of the diskette in drive 1, and change the 
default drive number back to 1. 

If more than two drives are in use, then additional controllers are 
required. These are placed in different slots than the first controller 
(which Is customarily in slot number 6). You can specify slot n (where n 
is a digit from 1 to 7) with the notation Sn separated from the file name 
or other disk options by a comma- For example, to initialize a diskette 
In drive 1 attached to a controller In slot 5, you would use the 
instruction 
INlT HELLO, S5, Dl 

The file name must come first, but order of the options is not important. 

The default slot number is the one you used when booting the DOS. Once a 
different slot number has been specified, it becomes the default slot 
number until it is explicitly changed. 

m 

After using a DOS command with a Slot parameter naming a slot that doesn't 
contain a disk controller, you get an 
1/0 ERROR 

message, and all appears to be fine. But DOS now thinks the default slot 

number is the bad slot number, and that the disk that isn't connected to 

that slot is still running . Even if the next DOS command specifies the 

ri fiV slDl ' lt V3lCft in l imbo forever tor the aO ft Afc lftttot disk to 

stop running the last command. If you have no program in memory that you 

care to save, simply re-boot DOS. To recover with your program intact, do 

this: 

1) Reset the default slot by typing 
CATALOG, Ss 

where s is the correct slot number. 

2) When the system hangs, press the RESET key. 
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3) Type 

3DJC 

and all should be fine again. 

DOS must be booted from a diskette in Drive ) not Drive 

The volume number option can be used to protect diskettes from being 
accidentally written over. For example, suppose your have a 
diskette-based Inventory system, where each month's records is on a 
different diskette with a unique volume number* Then when you go to enter 
Information for the month of January, you must be sure to specify the 
correct volume number. Otherwise, the information won't be written to the 
diskette and you'll get a 
VOLUME MISMATCH 
message* 

A "volume number" may be assigned to a diskette when it la IfflTlallzed» 
using the notation Vn separated from the file name or other disk options 
by a comma. For instance, to initialize a diskette using the name "START 
UP" for the greeting program {the program that is run each time the 
diskette is booted), where the diskette is in drive 2 of a controller in 
slot 5, assigning the diskette a volume number of 128, you would use the 
command 

INlT START UP, D2, S5, V128 

The volume number of a diskette may not be changed without re-INlTlallzlng 
the diskette. 

The drive number, slot number and volume number options may appear in any 
order. The above command is equivalent to 

INIT START UP, V128, S5, D2 

and to 

INIT START UP, S5, V128, D2 
and flo on. 

The volume number of a diskette must be an integer from I through 254- If 
no volume number is specified with INIT, a default volume number of 254 Is 
assigned to the diskette. 

m 

The command 
INIT HELLO, V0 

does not give any message, but assigns the diskette the default volume 
number 254. 

AM DOS commands can specify the volume number. If you wish DOS to check 
that the volume number on the diskette agrees with the V option. If you 
do not specify any volume number, or if you specify volume zero, or if 
you type "V" without a number, DOS will Ignore the diskette's volume 
number. If you accidentally specify ao incorrect volume number, the 
oyntem will reject It with the message 
VOLIIHK MISMATCH 
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Volume mismatch errors cannot occur when you ask to see the CATALOG. In 
case you wish to know the volume number ot a diskette, it is given at the 
head of the CATALOG listing. 

Additional discussion of options la found where each command Is 
Introduced. Also, the information is concisely summarized for each 
command in the Command Summary Appendix and on the Quick Reference Card 
accompanying this manual. The following section explains how to interpret 
these concise summaries. 



SYNTAX 

Syjitax refers to the structure of a computer command, the order and 
correct form of the command's various parts. A simple notation is used to 
describe the syntax of each DOS command. Items In brackets <( and 1) are 
optional; optional parts of a DOS command may be specified In any order. 
CAPITAL letters and commas must be typed as shown; lower case letters 
stand for Items you must supply. In specifying the syntax for DOS 



f stands for a file name 

d stands for drive number — either 1 or 2. 

s stands for slot number — 1 through 7. 

v stands for volume number — 1 through 254, usually. 

A diskette's volume number may not be 0. Specifying a 
volume number of in a disk command Is a "wild card" that 
tells DOS to ignore the volume number on the diskette. 



Additional abbreviations used in this manual are summarized at the start 
of the Command Summary Appendix. 

Any numerical constant (the drive number, volume number, etc.) in a DOS 

command can be expressed In hexadecimal notation by preceding the hex 
digits with a dollar sign. If you don't know what hexadecimal notation 

is, Ignore the preceding statement -- you need't understand hex notation 
to understand this manual. 



MIT 

The syntax for the IHIT command ia 
INIT f [,Vv] [,Ss] [,Ddl 

where the brackets indicate options which may or may not be included. The 
example 

INIT HELLO, V17, D2 

can be interpreted as follows. 

The command name "INIT" is in upper case, and must be typed exactly as 
shown. The lower case "f", for file name is replaced by the legitimate 
file name HELLO". Next the optional volume number is indicated: first 
comes a comma, then the upper case "V". The "v" for volume number was 
arbitrarily replaced by 17 for this example. The brackets around ",Ss" 
Indicate that specifying the slot number is optional for the INIT command: 
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In this example it's omitted so DOS will use the default slot number. The 

drive option in Included: the comma and upper case "D" must be as shown; 
the lower case "d" Is replaced by 2 In this example. 



LOAD, RUN AND SAVE 

LOADlng, RUNning and SAVElng programs on the disk is similar to the 
corresponding operations using the cassette (except that programs are 
referenced by file name)- Everything goes at least ten times faster, and 
you never need to press buttons to play, record or rewind* It is all 
automatic. There are many additional abilities that the disk brings as 
well, such as the catalog of programs and the automatic running of 
programs without user intervention- Saving data (on text files — see 
Chapter 6) is also very easy. The FID program described in Appendix J 
of fern you some additional ways to manipulate files- 
It's a good Idea to hang on to your caasette tape system for trading 
programs and as back-up storage for vital programs and data (although 
experience shows that disk storage Is even more reliable than cassette 

storage of programs and data). 

If you have a program in BASIC, and you wish to call it HENRY, then the 
i ommand 
SAVE HEHRY 

will save it on the diskette- If you have more than one drive, HENRY 
normally would be saved on the drive from which you booted DOS (the default 
drive, unless you specified a different drive after booting). You can 
specify drive number, volume number and slot number as with the INIT 
command. For example, to SAVE a file called AGATHA on drive 1 of the 
controller in slot 2, where the volume number of the diskette is 214, you 

could use the command 
SAVE AGATHA, Dl , S2, V2U 

As before, the three options can be put in any order. If you had omitted 
the volume number option, AGATHA would have been saved Just the same, bless 
her, but DOS would not have checked that the diskette was volume 214. 

Program names are file names, and must follow the file name rules: they may 
be up to 30 characters long, and must start with a letter- They nay 
include any characters you can type except commas or control characters. 
Here are some valid names for filea: 
CHECKBOOK 

THE QUALITY OF MERCY 
H1RES34 

NOW: HEAR THIS! 



To LOAD a program named AGATHA, use the command 
LOAD AGATHA 

m<i the program of that name, if there is one In the catalog, will be 
loaded. To test if AGATHA is loaded, see If she can walk a straight line- 

If you want AGATHA to RUN after she's LOADed (poor thing) you can, of 

e«U»«i uae the commands 
LOAD AH ATI I A 
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then 
RUN 

But there's a way to do it in just one step: 
RUM AGATHA 

is a DOS command that first LOADb the specified file, then ftUNs It. 

Here's the syntax for the SAVE and LOAD and RUN commands: 

SAVE f USsl (»M) I t Vv] 

LOAD f I,SsJ UDd] |,W] 

RUN f [,Ss) l,Dd) !»Vv] 

Examples follow: 

SAVE OUR HAPPY HOME, DI» S7 

LOAD UP 

RUN AMOK, S7 




If, when you try to SAVE a program , you get a SYNTAX ERROR message, 
either you have made a typing error, or DOS isn't booted- First, try 

re-typing the command* If DOS was originally booted, use 

3D(»G 

to try to recover- If DOS Isn't booted — DON'T BOOT IT. Booting DOS 
will erase any program In memory * First, save the program on tape, using 
the usual cassette 
SAVE 

command. Now boot DOS. Next, use the usual cassette 
LOAD 

command, to bring the program back Into your APPLE 11 's memory from the 
tape. Nov you will be able to SAVE it on disk. 

If a diskette is bad (perhaps someone tried to staple It into a notebook), 
or if the diskette is not initialized, or If there is no diskette io the 
drive, or if the door is open, the message 
I/O ERROR 

(I/O stands for Input or Output) will appear when you try to SAVE or LOAD 
using DOS. Check all the items listed, and correct the problem* You 
don't need to re-boot DOS. Try again. 

If you use the command 
LOAD HENRY 

and HENRY is not the name of a program on the diskette in the drive, then 
you get this message 
FILE NOT FOUND 

Look at the diskette's catalog to find the program's exact file name- All 
characters and spaces must be typed exactly as they appear in the file 
name shown in the catalog. 



DELETE 

To eliminate any file that you would 
command 

DELETE 

can be used. The syntax is 
DELETE f [,Sa] IJM] I.Vv] 



rather not have on your diskette, the 
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For examples command 
DELETE EXCESS, VM t DZ, SI 

deletes a file named EXCESS from a diskette with volume number 34, which is 
placed in drive 2 of the controller in slot U Sectors on a diskette arc 
"aet free" only when a file is DELETEd. 



A SCENARIO: BOOT, SAVE, RUN, CATALOG AND DELETE 

Suppose you're running Integer BASIC and the System Master diskette Is in 
your disk drive. Here's a dialog as It might appear on the screen of your 
APPLE II* The parts you type are underlined , although they do not appear 
tUnt way on the TV screen. First type 
> PR<6 

to clear the screen. You'll see the following: 

OG5 vCftSIQfc Jl «** 

** (ft* *fclLU 

**r mm WOTi* 
*f> my t*«im 

-ft mw cguav WW* 1 
- 1 HHP LtPV 

«* ms u#*> 

** ' *** |fi*WWt 

«* w< mwt ma 

m** u^Mtt 
•* «w> i* 

*« ifef PHI** LIST 

*** MftJ ttffrUCW TEX* 



. I At this point, you would insert the 

Slave diskette you INITiolized earliei 
since it is not write protected. 1 

1 0Of . 



^ t4Hu 
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MSN voujrm 

I Oft£ COUNT 
I «K£ V€TO 

NO £KD EWE 
JflBBCRMOCK 

>&B£X£_££2B 

E «<*: MKM.O- 

MOVING BEfWBI LANGUAGES: FP AND NT 

Suppose you've been using Integer BASIC* and you decide to write a program 
In APPLESOFT, or to use the computer as a calculator with floating point 
numbers (numbers with decimal points). To invoke APPLESOFT without 
clobbering DOS, type 
FP 

(that's all there is to it) and in a few seconds APPLESOFT will be up and 
running- The FP stands for "Floating Point", of course. (If for some 
reason Applesoft isn't available — it's not in firmware or on the 
diskette that's in use — then the message 
LANGUAGE SOT AVAILABLE 

will be displayed.) The syntax for the command is 
PP [,Sa) l.Ddl 

where the optional Slot and Drive parameters allow to to specify the drive 
containing Applesoft on a diskette. 

If you've been using APPLESOFT and DOS, you can type 
1ST 

(for "Integer BASIC") to return to Integer BASIC with DOS intact. The 

suntax for this command is simply 

INT 

without any parameters. You'll generate a 
SYNTAX ERROR 

message if you try to use the D or S parameters with INT. 

x 

If you type 
INT 

while In Integer BASIC , you will lose any program in memory. Similarly, 

if you type 

FP 

while in Applesoft , you'll lose any program in memory. 

Vhen you switch from Integer BASIC to Applesoft or vice versa, you'll lose 
any program you happen to have in memory* 
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In addition to moving back and forth between the Apple's BASICs, you say 
wind to enter the Monitor and be able to use DOS commands. To do so from 
a i the I Applesoft or Integer BASIC, type 
CAM, n|5I 

and yon should get the Monitor prompt character, * . To return to 
whichever BASIC you started from with your program and DOS intact, type 

Fn»m the Monitor, you may also type 
INT 

to return to Integer BASIC* or 

FP 

to return to Applesoft; in either case, DOS will still work but any 
projtram in Memory will have disappeared . 

x 

If you get n 
PROCRAM TOO URGE 

message when trying to execute an 
FP 

command, type 
INT 

first, to reset the system* Then type 
FP 




Even though your diskette contains the Integer BASIC program named 
APPLESOFT, do not type 
RUN APPLESOFT 

If you do, Applesoft will seem to be running fine until you press RESET, 
way, and try to re-enter Applesoft. Then, since the DOS thinks you are in 
Integer BASIC (because APPLESOFT was an Integer BASIC program), you will 
be in trouble. 

To move the APPLESOFT program from one diskette to another, simply 
WAD APPLESOFT 

from whatever diskette it's on, then place the diskette you wish to 
contain Applesoft In the drive and type 
SAVE APPLESOFT 



USE Of DOS FROM WITH IN A PROGRAM 

Very often it's useful to be able to execute a DOS command from within a 
BASIC program. For example, you may wish your greeting program on a disk 
to print out the contents of the disk by doing a CATALOG command. Many 
DOS commands can be executed from inside a BASIC program. This is done by 
PKINTfng a string that consists of a CTRL-D followed by the command. 

Hero Is an Applesoft program that, if used as a greeting program, will 
cause the Information In the PRINT statements in lines 20 and 10 to appear 
on the screen, followed by a list nf files In the CATAIW. 
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5 REH GREETING F*OGB*H 

10 M - CHW C4>; REM CMR*C4> 

IS CTRL-P 
20 PffINT "SLffVE DISKETTE CHERT ED 

3* PRJHT -BV flrtV toms ON 8 MJDU 

sr iw- 

40 PRINT D*> •tRTflLOQ" 

The recommended way to do this in Applesoft Is Illustrated in the above 
program* First the string D$» consisting only of a CTRL-D, is created 
using the CHRS function in the first line of the program. Later it can be 
used as in line 40 
40 PRINT DS; "CATALOG" 

Note the semi-colon after the D5 and the quotation marks around the DOS 
command. The semi-colon is optional in Applesoft PRINT statements, so if 
a program has many DOS commands in PRINT statements, you may find it saves 
typing time and memory space to simply omit them* and use the form 
40 PRINT D$"CATALOG" 

In Applesoft, you can use the CHRS function to specify CTRL-D 
10 D$»CHR$(4): REM CTRL-D 

But you need to recall that the ASCII code for CTRL-D is 4, so a REMark 
may be useful* (The CHRS function is not available in Integer BASIC*) 

In either Integer BASIC or Applesoft you may define CTRL-D by 

typing the characters 

DS B " 

then typing the letter D while holding dovn the CTRL key, and then typing 
the quotation mark, M . Not* that the CTRL-D does not print on your 
TV screen* The final command will appear as 
DS- M " 

Since control characters do not print, it'a often a good idea to follow 
with a REMark to remind you of what actually ia in the string. Here's the 
above program written in Integer BASIC: 

10 t*~ H * REM THERE IS RN IHVISIBL 

E CTRL-0 BETWEEN THE QUOTES 
2* PRIMT "SLAVE DISKETTE CREATED ON 

3SfK SVSTEH* 
30 PRIMT -OV flMV OQ**S OH * AUGUST 

40 PRINT t>fi "CRTWLOG" 
50 END 

Only one DOS command may be used in a PRINT statement. The PRINT 
statement must begin with the CTRL-D and end with the DOS command. 

Using the right-arrow to copy a BASIC statement containing an invisible 
control character will erase the control character- 
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In DOS co*nnnds executed by a program* the DS muat be preceded by a RETURN 
or it will be Ignored. RUNntng this program 



5 «H TESTCBTH.OG PRGGKftrt 
IP M « " PER THERE IS AN IMV 
ISIBLE CTBL-0 BETWEEN THE OU 
OTES 

M *WfNT "TCST-i 

2*1 PPINT -CATALOG" 

40 EW> 



will cause 
TESTCATALOG 

to be displayed, since the semi-coloo suppresses the RETURN at the end of 
the PRINT command In line 20. To correct this, and cause the DOS cocanand 
CATALOG to be executed when the program is RUN, Just delete the semi-colon 
(;) from the end of line 20. 

These DOS commands should only be used within programs in a PRINT 
statement beginning with a CTRL-D: 

OPEN 

APPEND 

READ 

WRITE 

POSITION 

These DOS commands may be used 
within a program using a PRINT 

CATALOG 

SAVE 

LOAD 

RUN 

DELETE 

RENAME 

LOCK and UNLOCK 
HON and NOMON 

The DOS romitand MAXFILE5 may be used as described above in an Applesoft 
program, but it must be used in a special way from an Integer BASIC 
program, as discussed in the section about the EXEC command in Chapter 7* 

Tb« DOS command INIT should be used only in Immediate-execution mode 
(Airv consequences may result if you ignore this admonition). 



in immediate-execution mode, and also from 
command with CTRL-D: 

BSAVE 

BLOAD 

BRUN 

EXEC 

CLOSE 

CHAIN 

PR* 
INI 
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Two ways of protecting you find/or your diskettes against disaster have 
already been mentioned. Chapter 3 Mentions using the Volume option to 
ensure that you place Information on the desired diskette. The use of 
control characters in file names can also be used as a way of protecting 
yourself (see Chapter 2» "What's in a Name?" and also Appendix F ( "File 
flames"). If what appears in the CATALOG as 
MY BANK ACCOUNT 

i fact has your initials placed as control characters at some point(s) in 



the 



nfltiw?, then it's unlikely that anyone else can access the fil« 



This chapter mentions a variety of ways of protecting you and your 
diskettes against various undesirable events. You'll probably find one or 
more of the techniques useful at one time or another. First, consider 
making a special purpose "turnkey" system* 



CREATMG A TURNKEY SYSTEM 

Suppose a doctor wants to do the office accounting on an APPLE II. 
Ideally, the office staff should be able to simply turn on the APPLE II, 
type 

{RESET} 6(CTRL>P {RETURN} 

and immediately be in the midst of the doctor's accounting program- Since 
the accounting program would (hopefully) communicate with the user in 
ordinary English, the staff wouldn't need to know BASIC or anything else 
about the APPLE II, The computer would become an accounting system, its 
internal characteristics unimportant since all the staff needs to know is 
how to use the accounting program. 



This is the essence of a "turnkey" system: from the user's point of view 
the computer is a device that does only a particular task, and getting the 
system started is as simple as turning a key in a lock. In this case, the 
"key" is sfmply turning on the Apple's power switch and pressing five keys 
on the keyboard. It does not require computer expertise to be able to do 
that. 



You can use the diskette's "greeting program," named when you INITialized 
the diskette, to turn your APPLE II into a turnkey system. Let's aay that 
you wanted the computer to run the COLOR DEMO program (provided on the 
System Master diskette) every time you booted Disk II. Here's how: 

1) INITialize a blank diskette, as described in Chapter 2. 

2) place the System Master diskette in your drive and type 
RUN COLOR DEMO 

Once you're satisfied that the program RUNs correctly, type 
(CTRL)C 

to stop the program and return to BASIC. 

3) Put your newly initialized diskette into your drive. We'll 
assuoo that you called your "greeting" program HELLO when 
you INITlallzcd the diskette. 

4) The program COLOR DEMO Is now in nwraory. When you type 
SAVE HELLO 

DOS will erase your original greeting program named 



34 



HELLO nnd save the COLOR DEMO program under the HELLO 
file name. The COLOR DEMO program is now the greeting 
program on your diskette* 

To check that all works as expected, boot the disk. 

You should get the same program chat you used in step 2). 



You've just created a turnkey system: whenever that diskette Is booted, It 
will automatically LOAD the COLOR DEMO program and RUN it* 



LOCK AND UNLOCK 

Sometimes you'll want to prevent a particular program from accidentally 
being erased from a diskette: the LOCK command will do this for you. 

Example: 
LOCK HESS, D2 

The CATALOG of this diskette's contents will now show an asterisk { * ) 
ne\t to the entry for HESS. 

If you decide you no longer wish to keep the file LOCKed* the UNLOCK 
command will (surprise!) unlock the file- 
Example; 
UNLOCK NESS 

The syntax for the commands is 

LOCK f USs] UDdl [,W] 
UNLOCK f [,Ss] f.Dd] I,Vv] 

The interpretation of the notation is discussed in the Syntax section of 
Chapter 3. 

If you try to DELETE or REKAME a file that's LOCKed you'll receive the 
message 

FILE LOCKED 

You'll also see this message if you try to SAVE a file using the name of a 
LOCKed file (if the file you're trying to SAVE is in the same language as 
the LOCKed file). 

If you try to SAVE a file using the name of a LOCKed file in a different 
lnnguage* then you'll receive the message 
FILE TYPE MISMATCH 

Try again, using a different file name. 



VERIFY 

Occasionally Information may not be recorded correctly on a diskette* 
This may happen if the diskette is scratched or dirty, for example. The 
VERIFY command reports a file which may be damaged or written incorrectly. 
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The syntax is the usual one for DOS commands: 
VERIFY f (,Ss) f.DdJ |,Vv] 

Examples of the way to use the command follow: 
VERIFY SAM 

VERIFY FINANCE-8,D2,V22 

VERIFY checks to set- that information in the specified file Is 
self-consistent- If it is, you see no message: the prompt character for 
the language you're using is simply printed: 
> for Integer BASIC 
J for Applesoft 
* for the Monitor. 

However, VERIFY doesn't check to see whether or not a program Is 
clobbered. If you SAVEd a program that was messed up somehow, it will 
at 111 be messed up on the diskette, and it will still VERIFY - 

If the VERIFY command finds an error, the 
T/0 ERROR 

message is displayed. 

If you try to VERIFY a file that isn't on the disk, the message 
FILE NOT FOUND 
is presented. 

You can use VERIFY from Integer BASIC, Applesoft, or the Monitor. From 
these languages you may VERIFY any type of file. Including text files (see 
Chapters 6, 7 and 8) and machine language programs (see Chapter 9). 



WRITE-PROTECTING A DISK 

The LOCK command allows you to protect a particular file. But sometimes 
you will want to be sure that all files on a certain diskette are not 
accidentally written over, and thus lost. To "write-protect" a diskette, 
you merely need to cover up the squarish write-protect cutout in the side 
of the disk. Stick-on adhesive labels are supplied for this purpose when 
you purchase diskettes but, in a pinch, any piece of sturdy tape will do. 
Note that the System Master diskette does not have a write-protect cutout: 
it is permanently write-protected. 
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If you deride you want to re-use a write-protected diskette, simply remove 
the label (often railed a "tab") that covers the write-protect cutout. 

Some programs r.mnot bo used with a write-protected diskette. An example 
of such a program Is ANIMALS, one of the demonstration programs of the 
System Master disk. Put your System Master in your drive, and boot DOS if 
you need to. Now type 
LOAD ANIMALS 

which will put the program into memory. Now type 
RUN 

«nd the message 
WRITE PROTECTED 
STOPPED AT 1040 

will be displayed. ANIMALS won't RUN on a write-protected diskette 
because it saves information on the diskette each tine you play the game. 
When you RUN the program, the diskette in the drive must not be 
write-protected, else the information can't be written on the diskette. 

Now ANIMALS is in memory, but you can't RON it with the System Master 
diskette. Put an initialized diskette, one that is not write-protected, 
in the drive. Next type 
RUN 

and now you can play ANIMALS, a game that will "remember" what you "teach" 
it by saving the information on the diskette. When you're through 
playing, type 
SAVE ANIMALS 

so that you'll have the game on a diskette that's not write-protected. 

If you type 
CATALOG 

you should see that you have not only a copy of ANIMALS on the diskette, 
but also a new file called ANIHALSFILE that was created by the program 
ANIMALS. 



PROTECTING YOURSELF AGAINST DISASTER 

Floppy disks are sturdy and reliable compared to some other ways of 
storing computer programs — for example, on the backs of old envelopes. 
But it's still possible to lose or destroy all information on a diskette. 
A diskette nay get scratched or damaged by heat; it may get lost, or a dog 
may chew it; someone may decide to use it as a frlsbee at the beach; if a 
diskette isn't write-protected, it may accidentally get written over. And 
a diskette will eventually wear out — a lifetime of 40 working hours is 
about average. 

** Moral ** 

Ke*p more than one copy of a program around if you don't want to lose it. 
In r<»npuicrese, "back up" any valuable program, 

jS ^3 If y«u are in the midst of writing or modifying a program, one way to back 

» up the program Is to keep copies of earlier versions. Then if the current 

version iH lost you can fall back to the next-most-recent version, and 
IP* hopefully not lose too much programming time. One good way to do this is 

v 



co end each file name with a mistier which changes from version to version. 
For example, suppose you start to write a program called FINAKCF. The 
(ln»t time you save the program, call It FINAHCE-1 - Next time you work on 
the program. Have it under the name P1NANCE-2; the third tine, it becomes 
FINANCE- 3, and so on- You'll wind up with a whole collection of FINANCE 
programs, with the largest version number representing the aost recent 

version of the program* 

It's a good idea to SAVE a developing program periodically (with a new 

version number)* If you do this every 15 or 20 minutes, an unexpected 
power failure or other disaster will not erase all your work- You can* of 
course, immediately continue working after SAVEing the current state of the 

program " just be sure to assign a new version number for the next SAVE- 
If the diskette starts filling up, DELETE some of the earlier versions- 
But it's a good idea to keep several versions around* In case something 

calamitous happens to the current version- Or you may Just happen to want 
an earlier version — not all revisions are improvements* 

The phrase "backing up" is also used to describe keeping multiple copies of 
programs on separate diskettes. There are two approaches to backing up in 
this fashion. The first method, using one disk drive, is to simply SAVE 

the program on one diskette, remove that diskette from the drive, insert 
another diskette and SAVE the program again. 

The second approach involves duplicating all the information from one 
diskette onto a second diskette. Details of the second approach are 
discussed in the next section. 

USING THE COPY PROGRAM 

You can use the CHpY program, on the System Master diskette, to copy the 
entire contents of your current programming diskette onto your back-up 
diskette. If you are using DOS from Applesoft Basic, COPYA is the program 
to use for copying a diskette. 

In these copying progratts, the diskette from which copying is done is 

called the "original" diskette. The entire contents of the original 
diskette will be copied onto a "duplicate" diskette. The duplicate 

diskette does not have to be INTTialized before being copied onto. In 

fact i any previous information that was on the duplicate diskette will be 

erased. 

Before copying the original diskette, it's a good idea to urite-protect 
it. Then you can't accidentally erase its contents, even if you put it 
Into the wrong drive- 
As default values, the program initially assunes that the original diskette 
will be placed In the currently selected drive (the drive from which you 
ran COPY or COPYA) connected to the controller card in the currently 
selected nlot. The duplicate diskette is assumed to be in the other drive 

connected to the saw controller card (even if there isn't another drive 
there). To use any of these default slot or drive numbers, just press the 
RETURN key when the default nunber is shown. If any of the default numbers 
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are wrong, either for the original or for the duplicate diskette, you must 
type the correct number when you see that default number on the screen- 
Here's an example of using the COPY program on an Apple with one disk 
drive- It assumes your disk drive is attached to a disk controller 
card in the same slot as the one from which you ran COPY. 

1) Place the System Master diskette in the currently selected drive. 
Type 
RUN COPY 

(RUN COPYA from Applesoft) and after the usual whirring you should see 

^pPLt DfSKTrlfc DUPLICATION PPOQPrW 



ORIGINAL SLOT; CCPfMAT » € 

2) To use the program's default slot number* slot #6 in this example, 
just press the RETURN key* 

3) When the message 

WIVE DEFAULT * 1 

appears, press RETURN. 
A) Prcs RETURN again when you see 

DUPLICATE SLOT* DEFAULT » 6 



5> When you see the default drive number for the duplicate diskette: 

E*fVE DGFttULT • 2 

type 1. 

6) The message 

— press PtrypN' >xv to begin ccw — 

will appear. This Is your signal to remove the System Master diskette 
from the drive and insert the original diskette, from which you wish 
to copy. (Did you remember to write-protect your original?) 

7) Now the program will proceed, first by directing you to insert your 
original diskette, then by informing you that it is reading Information 

from the original diskette. Then the program will let you know when it 
la ready for you to replace the original diskette with the duplicate 
diskette in the drive, and when it is formatting (INITialising) that 

diskette. After the duplicate diskette ia INITialited you will be 
Instructed to re-insert the original diskette so that the program can 
read some sore information from it, and then to re-insert the duplicate 
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diskette ao thM the Information can be copied onto it. These two steps 
will have to be repeated until the entire original has been copied. 

) When copying Is complete you'll see the message 

l.4 v v .ni put** re mice flWlHR copv? 

If yoti type Y (yes), the copying procedure will be repeated, assuming 
the san* locatlon(s) for the original and duplicate diskettes* Be sure 
to re-Insert the original diskette when you see 

— H«SS RETURN' KEY TO BEGIN COPV — 

and that you use another diskette (either a blank or one with unwanted 
information on it) as the duplicate. If don't vish to make another 
*°py* type N- You will leave the program and DOS will assume your 
default disk drive to be the one which was the location of the duplicate 
diskette* 



If you hiUfe core than one drive, specify the slot and drive numbers for 
the original and duplicate diskettes and insert the diskettes in these 
locations hefore the copying oegins. Note: If you have more than one disk 

drive, the system won't prompt you to remove and replace diskettes. It 

only does that for single drive copying. 




If you try to copy onto a write-protccted diskette you'll see the message 
I/O ERROR 

STOPPED AT (you'll see a line number here) 

Until the vrltc-protect label is removed from the duplicate diskette no 
information can be put onto the diskette. 

An I/O ERROR or UNABLE TO READ message will also appear when the drive 
door is open or if there is no diskette in the drive. These messages may 
also indicate a problem with the diskette in the drive. Be aware that the 
default drive number ray hove been changed after you have gotten one of 
these message*. When you RUN the copy program again, you may have to 
specify th e drive location of the System Haster diskette. 
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DEBUGGING: MON AND NOMON 

The process of trying to get a program to run the way you want It to Is 
called "debugging;' 1 program errora are often referred to as "bugs"* All 
disk commands and all Information gent between the computer and the disk 
are normally not displayed on the screen* But when you're debugging, 
monitoring this Information can help you track down problems. 

The HON command allows you to MONitor a variety of Information* To turn 
various parts of the display off again, use the NOMON (HO HONltor) command. 

Three different parameters that may be used in these commands: 

C stands for Commands to the disk (such as OPEN, READ, etc) 

I stands for Input from the disk (when READiog a file) 
stands for Output to the disk (when WRITEing a file). 

These parameters are used only with the NOMON and HON commands* Usually 
NOMON C,I,0 is in effect: no monitoring is taking place* 

The syntax for the commands is 

MON [CI M] [,0| 
NOMON (CI M] NO] 

At least one of the three parameters must be present with the NOMON snd HON 
commands, else the command will be ignored- The parameters may appear in 
any order and, as usual, must be separated by coonas. 

There are 7 different ways in which the MON command may be used: 



command 


what it monitors 


MON C 


Commands to the disk 


MON I 


Input from the disk 


MON 


Output to the disk 


MON 1,0 


Input from and Output to the diak 


MON C,I 


Commands to and Input from the disk 


MON C,0 


Commands to and Output to the disk 


HON C f I,0 


Commands to, Input from, and Output to the disk 



*« NOTE *** 
A HON command remains In effect until a 
NOMON, INT, or fP (firmware only) command is encountered 

or 

until you boot the system 
or 

do a restart (3D0C)> 
or 
RESET 

A neat trick: you can issue a HON command and later cancel it without 
affecting the screen format " even the NOtiON does not show on the screen. 
Suppose you execute a MON command, say 

MON C, I, 

To cancel the command without having it print on the screen, include 
PRINT DS; "NOMON C,1,0"; VTAB PEFK{37); CALL -868 
where DS. as usual- contains CTRL-D. 
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MAX FILES 



DOS allows up to 16 files to be active (in use) at one time* DOS deals with 

several types of flies in addition to the BASIC program files discussed so 

far. See Chapter 6 for a discussion of sequential text files. Chapter S for 
random-access text files, and Chapter 9 for the DOS coomnds used with 

binary (machine language) files. 

The HAXP1LKS command specifies how many active files are permitted. When 
you boot DOS, the command 
MAX FILES 3 

la executed, which sets up the default condition; a maximum of 3 files may 
be active simultaneously until another MAXFILES command is executed. 

The command's syntax is 
MAXFILES n 

where n must be an integer from 1 to 16. Specifying a value outside this 
range will cause a SYNTAX ERROR message from either Applesoft or Integer 
BASIC; from the Monitor, a beep ta the only indication that you've done 
something wrong- 

For each file specified, MAXFILES sets aside 595 bytes of memory space called 

a file buffer. This additional memory apace for each active file la used to 

help adjust for the fact that memory speed is far faster than disk access 

speed, rtlch involves mechanical motion -* the disk head has to search the 

diskette. So in the name of efficiency, a file buffer is used to "buffer" 
information going to and from a diskette. 

If you retrieve information from a diskette, DOS brings In 256 characters at 
a time and puts them in the "input 1 ' part of the file buffer, then delivers to 
you whatever subset of those 256 characters your program requested. If you 
are sending information to a diskette, characters are stored in the "output" 
part of the file buffer until 256 characters have accumulated, then they're 
shipped to the diskette all at once. 

Suppose you have MAXFILES 1 and one file is active* An attempt to perform a 
DOS cossund (such as CATALOG) will cause the message 
NO BUFFERS AVAILABLE 
to be displayed. 

When the system is booted, the nunfcer of active files (n) defaults to 3, so 
1785 bytes of memory are reserved for 3 file buffers. Under scat 
circumstances, you won't need more than 3 active files. If mre files are 
requi red, type 
MAXFILES n 

(where n Is the nuofoer of needed files) in immediate execution mode before 
loading and running a program* 

m 

In immediate execution mode, changing MAXFILES eraaea Integer ft ASIC 

programs and Increasing MAXFILES messes up Applesoft strings, since HI MEM: 

la nuved down without moving the program or strings. To avoid the problem, 
reoet MAXFILKS before loading and running a program. 
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If MAXFILES is used within a program, it changes memory pointers, and i 

GOTO, CO SUB, or other instruction can get lost- If you must change 
MAXFIUtS from within an Applesoft program;, make the MAXFILES command the 

first statement in the program, before any string variables are declared* 

For example, 10 PRINT CHH$(4); "MAXFILES 5" r : 

To use MAXFILES from within an Integer BASIC program, you need to create an 
EXEC file, as discussed at the end of Chapter 6- 



TRACE 

The Applesoft TRACE caamand is a useful debugging tool- But when TRACE is In 
effect, DOS commands inside Applesoft programs don't work because TRACE 
prints the line number before the D05 command- There's a partial solution 
to the problem- You can insert a RETURN (that is, CHR$(I3)) in the D$ 

string Ifl D$-CHRS<13)4CHftS<4> 

and then moat DOS commands will work properly even if TRACE is in effect — 
see the exception below* 



If TRACE is in effect and DOS tries to READ an INPUT from the diskette, your 
program will instead stop and wait for INPITT from the keyboard, which limits 
the usefulness of TRACE in connection with DOS* 



USING THE MASTER CREATE PROGRAM 

As discussed in Chapter 2, INIT is used to create slave diskettes- In this 

section you'll learn how to create master diskettes. The distinction 

between a slave and a master is not readily apparent: both come charmingly 

attired in the latest in black plastic (no, not leather) garb- It's up to 
you to revise your greeting program and diskette label to remind yourself 

which is slave and which is master. 

The System Master diskette contains a program called MASTER CREATE that can 
run on an Apple II with at least USE of nemory. The MASTER CREATE program 
does the following for you: 

* Corwerts a slave diskette (whose DOS is memory-size dependent) 

into a master diskette (whose DOS Is self -relocating so that 
memory is used efficiently on any siase system). 

* Gives the converted diskette a new greeting progran name, the nam* 
DOS will attempt to RUN each time the diskette is booted. 

The MASTER CREATE program must be used with a diskette that has already 
been INITtalitcd. It will not work with a diskette that is write- 
protected - 
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Here's an example of how to upgrade the diskette INITlalized in Chapter 2 
(the one with the ONE TO TEN program on it) to convert the slave diskette 
created by I NIT Into a master diskette. For convenience, that diskette 

will be referred to as diskette ONE in the discussion that follows. 
Before uaing MASTER CREATE, do the following: 

1) Insert the diskette you wish to convert — diskette ONE for this 
example Into the disk drive, and RUN the diskette's greeting 

program — named HELLO on diskette ONE* The message displayed by 
a greeting program should include the version of DOS used to 
Initialize the diskette, and its status as slave or master. 

2) Change the appropriate linea of the greeting program to display the 
new information, "MASTER DISKETTE*'. Then SAVE this new version of 
the greeting program. If the diskette's outside label requires a 
similar change, make that change now- 

3) 

Note the name of the greeting program. If you wish the converted 
diskette to RUN this same program each time it la booted. Just aa It 
did before converting, you will give this greeting program name to the 
MASTER CREATE program, later on* If you've always wished your 
greeting program had some other name than its present one, RENAME 
the greeting program now. Later, you will give the new name to the 
MASTER CREATE program. 

To use MASTER CREATE, do the following; 

ft) Put the System Master diskette in the drive, boot DOS, and 
from either BASIC type 
BRUN MASTER CREATE 

5) You should see the message 

iK& 3 t 3 rtf*5?Eff-f*E«TE UTILITY 
odpwght &v *ppl£ ODrrtiTEfi IMC- 

nu_ r&qht$ nesraveb 

^NOk COWLING DOS IW*tt£> 

6) You'll then be told to type the greeting program name 
to be used by the converted diskette: 

PLEASE INPUT THE GWEtVIMG PSOQPtWS 
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We'll assume that when you SAVEd the revised greeting program on diskette 

ONE (stop 3, above) you used the name HELLO. So type 
HELLO 

unless you wish the diskette to RUN some other program name each time the 

diskette is booted- When you press the RETURN key to enter the greeting 
program name, you'll see this message: 



RElCrtSBf THftT tWSTE* DOES NOT CRJEftTF 
(ME GREET IMG OP PLRCE IT IN 

THE DISK l>I*S:CTOffV 

THIS IS TMC FltE M«MC WRT WILL BE 
njKtfS WITHIN THE IH*Q£ 
HELLO 

PLKB THE 1>*S*£TTE TO B€ NftSTEfiEO fW 
TeC DISK DRIVE 

psess o?eturk> t#o* rctov 

NOTE : IF VOU URNT ft DIFFERENT FILE ttflflE, 

fwbs <£$& 



7) Follow the instructions- Remove the System Master diskette from the 
disk drive and replace it with the diskette you wish to convert — 
diskette ONE in this case. Finally, press the RETURN key to begin 
converting; the program will inform you when the process is complete. 

6) After using the MASTER CREATE program, always re-boot DOS before 
doing any other work. 



*** Note *** 

The greeting program name that you give to the MASTER CREATE program is not 
placed in the diskette's CATALOG. It just tells the diskette's DOS which 
program name to RUN each time the diskette is booted- You must make sure 
that the diskette's CATALOG actually contains a program bearing the sane 
name you give CO the MASTER CREATE program* 

If you forget to do so (by skipping step 3 above), you'll see the message 
FILE NOT FOUND 

each time you boot the disk using this diskette. 



*** Reminder *** 

You must remember the name of the greeting program for each diskette- 
Using the same greeting program name on all of your diskettes wakes this 

easier- 
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CHAPTER 6 




41 Text Hl-.i An Introduction 

Stqumtlal m.*t So*. EunplM 

48 OMMiBft and CLOSBlruj laouontLl flic* 

S« WITSiBB Sequential FUm 

64 WAQing S«fu«f>tt«l ttlm 

46 K«« (w £tequ»nrul rilw AWoro mod POSITION 

69 >yt*-iog Off ftor. 






TEXT FILES: AN INTRODUCTION 

Sometimes you'll want to use the disk to store Information that is not a 
program. You nay, for example* wish to keep copies of correspondence, a 
list of words used In a word-guessing game, intermediate results of a 
calculation, or a mailing list. A text file , sometimes called a data 
file will allow you to do this and more- The letter T marks text files 
in the CATALOG directory* 

T«Xt files are created and retrieved using DOS commands in an Integer 
BASIC or Applesoft program. A text file may be created using a program 
written in one language and retrieved from a diskette using a program 
written in another language- 
Most sample programs in this manual are in Applesoft. If you wish to 

convert the programs to Integer BASIC, recall that in Integer BASIC you 

can't make string arrays and you must DIMension string variables. In an 

Integer BASIC command such as 

INPUT AS, B$, CS 

only RKTURNs (not commas) may separate the three responses. This manual 
does not tell you how to make each program run in Integer BASIC: see the 
Appendix M of the Applesoft II BASIC Programming Reference Manual for 
details of converting between languages. For some hints about changing 
the BASIC in which a program runs, after the program has been written, 
see page 76 of this DOS manual. 



The DOS commands LOAD and RUN (also BLOAD and BRUN) may not be used with a 
text file. An attempt to do so will cause the message 
FILE TYPE MISMATCH 

to appear. LOAD and RUN expect a BASIC program file (and BLOAD and BRUN 

expect a Binary machine-language file), not a text file. Instead, you 

must write programs that send data to a text file and retrieve data from a 

text file, using the DOS commands discussed in this chapter: 

OPEN 

CLOSE 

READ 

WRITE 

APPEND 

POSITION 

EXEC 

The commands OPEN, READ, WRITE, APPEND and POSITION cannot be used in 
immediate-execution mode. If you try to do so, you'll receive the message 
NOT DIRECT COMMAND 

These commands oust be used in deferred-execution mode, that is, from 
within a program. The commands CLOSE and EXEC may be used in 
immediate-execution mode. 

In addition to the commands listed above, the DOS commands 

LOCK and UNLOCK 

DELETE 

RENAME 

HON and ROHM 
VERI FY 
CATALOG 

work with text files in the same way they work with program files. 
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There are (wo different types of text files: sequential text files and 
random-access text files. Both types of text files store strings of ASCIt 
codes to represent the data, but in different formats- Diagrams of the 
tvo text-file types are shown below (the character J represents the 
RETURN character, sent automatically at the end of most PRINT statements). 



"PICTURE" OF A SEQUENTIAL TEXT FILE 



111* 


A 


T |> |0 |N |E > |B | L | |W | > | | 


1 


1 


1 


1 1 


lEBEBQJClEEfDEJiaiBCaEQEDCDIBriilUIUCUIULLJCU 



ASCII: 

File Byte: 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 

Field: 9 1 2 ' 3 ' 



"PICTURE" OF A RANDOM-ACCESS TEXT FILE 
( Exanple: Record Length 5, One Field per Record > 



Character: 


7 


~ | 


|a 


T 


>l 1 


N 


■ > 1 




B |l |o 






























ASCII: 


1" 


|13|00|00 


W[bb 


84 


13|00 


(00 


|79|78 


|69|13| 


M 


|6* 


: 76 1 79 187 1 13 


File Byte: 





1 2 3 


4 5 


6 


7 8 


9 10 11 


12 13 


14 


15 


16 17 


18 19 20 




The terms "field" and "record" will be discussed in Chapters 6* 7 and 8. 
The commands OPEN, CLOSE, READ, WRITE and POSITION are used with both 
types of files, but in somewhat different ways. Sequential text files are 
simpler to use and understand* in some respects, so we will discuss the 
use and structure of sequential text files first. The use of 
mndom-access text files is described in Chapter 8. More detailed and 
technical information about all types of files can be found in Appendix C. 



SEQUENTIAL TEXT FILES: SOME EXAMPLES 

Suppose you want to make a file containing a list of words to be used In a 
word-guessing game. Here are two pairs of programs that deal with such a 
lile. The first program in each pair creates a text file on the diskette. 
The second program in each pair retrieves the data stored in the text 
[lie from the diskette. 

This program creates a text file named WORDS 1, containing the words APPLE, 
BANANA, CATALOG, DORMANT. EAGLE, FRUIT, GOOSE, HAT and ICICLE, 
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«t HEM f**'X M0RDS1 

^ M * PEN 

a> PRINT "OPEN WORDS!" 

4f» PRINT "WRITE M0RPS1" 

!W PRINT "APPLE" 

60 PRINT •BflNRWfi'* 

,T* PRINT -CftTfiLOG- 

89 PRINT -DORrtHNT* 

* PRINT -EftQLfi- 

it» PRINT "FRUIT" 

116 PRINT "OOOSC" 

12© PRINT *HRT- 

130 PRINT MCICCE" 

140 PRINT M "CLOSE W0RDS1- 

150 END 

Line 30 OPENs Che file, using the normal format for sending a DOS command 
from within a BASIC program- OPEN places a text file named V0RDS1 in the 
CATALOG (If it was not there previously). 

Line 49*8 WRITE com&and causes subsequent output from PRINT statements to 
be sent to the named text file Instead of to the TV screen- So in this 
program, each PRINT statement in lines 59 through 130 will send the word 

inside the quotation marks to the text file V0RDS1, and not to the TV 

screen - 

Line 140 CLOSEs the file, and ends the file-writing process - 

If the program is RUN and you're not in MONitor mode you won't set 
anything: usually DOS commands and disk input and output are not 
displayed. But if, as explained in Chapter 5. you type 
HON C, I, 
(or simply 
HON C, 

since no input from the disk is involved) and then you RUN the above 
program you'll see the following: 

OPEN MORC'Sl 
WRITE WORDS1 
fTPLE 

DORMRNT 

fcflGLfc 
FRUIT 
GOOSE 
Hf»T 

ICItXC 

CI.OSE U0RDS1 
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At this point you'll have a file called W0RDS1 on your diskette. WORDS I 
will be marked with a "T" in the CATALOG to indicate that it's a text 
file- The file consists of items of data (in this case, words) separated 
by RETURN*. A RETURN character is automatically sent at the end of every 
PRINT statement which does not end with a comma or a semicolon. Note that 
in this sense each RETURN Is a character rather than an pet ton ™ in 
particular, it la the character with ASCII code 13. 

Each item of data, ending with its RETURN character* la called a field . 
A field la stored in the text file as a aeries of characters represented 

by their ASCII codes* The last character in each field must be the RETURN 
character, ASCII code 13. 

WORPSI ia called a sequential text file because each field is stored 
beginning immediately after the RETURN character of the preceding field. 
When stored on the diskette* fields may be of different lengths: the word 
APPLE takes 6 bytes (one for each letter plus one for the RETURN 
character), KANAKA takes 7 bytes, and so on. A sequential text file is 
stored on the diskette aa one long, continuous series of ASCII~coded 
characters, a chain of fields with no gaps left between them. 

Once W0RD51 is on the diskette, the question immediately arises, "Now can 
I retrieve It?" The following Applesoft program will retrieve WORDS1: 

lO REH RETRIEVE MGRDS1 
MM- " RCH CTRLH> 
39 PRINT p*- "OPEN WORDS! - 
4rt PRINT D#, *RE«£> WORDS!" 
W POP I - 1 TO 9 

INPUT «*<!> 
79 NEXT I 

90 PRINT -CLOSE WJROSl" 

» END 

Line 30 OPENs the file; line Ad tells DOS that all subsequent INPUT or GET 
statements will refer to the named diskette file instead of the Apple's 
keyboard* It Is as if the disk were typing responses. Instead of you. An 
INPUT command always causes one complete field, ending with its RETURN 
character, to be "typed in" to the Apple. If another INPUT command 
follows, it will cause the next field to be read In, and so on- So 
lines 5fl through 79 cause DOS to start at the beginning of WORDS I and 
retrieve 9 fields which are placed in the array AS(1), A${2), AS(3>, 
AS(M, AS(9). tine 60 politely CLOSEs the flic. 

If HON C r I, la not in effect when the above program is RUN, you will 
see nothing on your screen. But if HON C» I, O (or just HON C, I) i£ in 
effect, you'll see 

OPEN *t*T>S 1 

REACV uorosi 

wfii 

■^PHNHNR 
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Toocsc 

A question mark ( 7 ) Is displayed before each INPUT from the disk, just 
nB It Is before each normal keyboard INPUT. 

To check that all worked as claimed, try typing 
PRINT AS(2), AS(9>. A$(S) 

and you should see the words BANANA — from A$(9> — then ICICLE and 
finally DORMANT. This Is a good way to check that information was read 
correctly. 

If you modify Che program MAKE WORDS 1 to make different words, be sure to 
DELETE WORDS I before re-RUNning MAKE WORDS I . If you don't, you nay end up 
with a mixture of the old words And the new. 

Here's how to create a sequential file called VORD52 containing the same 
words as WORDS 1 1 but with all nine words in one field. Each word is 
followed by a comma, so that an INPUT statement with multiple variables 
(9 t In this case) can be used to retrieve the separate words. 

X ft* * REft Ctfl^K? 

JO Mi INT Mj "OP£N MORC«S£* 

prj«t - e«NflNft, £«t*lo 

■ 

t» fwjmt * owst. hut, tcicu^ 
» nrmr m* "close hd«>w* 

90 rrj. 

Note that the PRINT command in line 59 ends with a seal-colon. A 
semi-colon at the end of a PR1KT command stops the automatic printing of a 
RETURN character after the last data character. Therefore the characters 
sent to the disk by the next PRINT command will appear in the same 
ricld with the characters sent by line 59's PRINT command. The PRINT 
command in line 6fl also ends with a semi-colon* so the field still docs 
not have its end-marking RETURN character. Line 7fl's PRINT command ends 
without a semi-colon or com, allowing the automatic final RETURN 
character to be sent at last. This ends the field, which now contains all 
the characters PRINTed by lines 59, 60 and 79. 
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* in i in n dtsk-lesn PRINT command usually send characters to defined 

tfib-fields on the screen. However a commas do not serve this flame 
fnrmattlnK function in PRINT commands used when WRITE ing to the disk: 
ih«>ftc rommns are treated as if they were semi-colons* in PRtNTing to the 
dlak. Herns separated by commas will be concatenated, with no intervening 
spaces Inserted. A comma at the end of a PRINT command has the same 
effect as a semi-colon: no automatic final RETURN character Is sent. 

When the program HAKE W0RD52 is RUN with HON C, T, in effect, you'll see 

UP1TE WOftVTCf 
IW« WWHNfl. CATALOG, WWWT. EfGLC, 

FfmfT' Goose, hrt. rrifxc 

CLOSE 

This Applesoft program retrieves WORDSZi 

Zm O* » "j RED CTRL-P 
3fl PfilNT "OPEN 
40 PRINT M; *B£» 

se input m*iAZ*»««3»^ P5« , a»* 
* «7i. nes< A9f 

« PRINT -CLOSE WDW>S£ H 
9* £NP 

When the above program is RUN with HON C, I t In effect, you'll aee 

0P€N 

? flPPLC SrtNflNft. CATALOG* POWfWNt, EftOLE 

. F*UJT, Q0OSC- HRT. ICICLE 

CLOSE 

In Integer BASIC, commas can separate multiple INPUT responses for 
numeric variables, but not for strlnR variables. Only RETURN 
characters can separate multiple responses when INPUT is used with 
multiple string variables. In Integer BASIC, therefore, the program 
RETRIEVE WORDS 2 will assign the entire field (9 words, 8 commas and 6 
spaces) to the variable Al$. Then you will get the END OF DATA message 
when there is no field to assign A2$. 

In Applesoft BASIC, you can also use the GET command to retrieve data from 
a tent file, character by character. This has the advantage that you can 
define an^ character as marking the end-of-word, for instance* The 
following Applesoft program also retrieves the tent file WORDS?. 

In Una 19, the CLEAR command sets all variables (including 1 and all 

A5( 1 >*«> to zero. Line 29 uses Applesoft's altercate way of setting DS to 

CTRL-A (4 Is the ASCII code for CTRL-D) • This method avoids the invisible 

(and un-copyable) control character. 
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' 1 

« If M * " " TMfiS aare r$ 
GOTO 3# 

154 Mt|W* H#/»> "C4-0?£ W*Wfe" 

Line 80 CETs one character at a tine from the text file WORDS 2, which was 
OPENed for READing in linos 5* and 60* If the new character is neither a 

coatma nor a RETURN » line 110 adds the new character to the end of the 
string AS(I)- Then lino 120 sends the program back to line 60, to GET the 
next character* Thus* the program builds up the first word, character by 

character* in AS(D- 

When a ccxnma Is found the first word is ended* so line 90 sends the program 
back to line 70 to increment I and start collecting a new word fn A$(2)« 
And so on* Finally, a RETURN character (R$) marks the end of the field, 
so line 100 sends the program on to line 130 to CLOSE the file and end the 
program- Note the use of CHRS(L3)» in line 30. You cannot directly type 
a RETURN character into a BASIC program line (a typed RETURN ends a 
program line), but CHR$(13) is a RETURN character in Applesoft* 

When GET obtains characters from the disk* these characters are not 
displayed on the screen, even in K)H C, I, mode* Line 115 has been added 

to let you see the words as they are built up. character by character. 

$ 

After an Applesoft GET command takes its response from a diskette text 
file, the following problems arise: 

1) With NGMON C,I.O the first character PRINTed after the GET 
will not appear on the screen- 

2) With WON 0,1,0 the first character PRINTed after the GET 
will appear on the screen. 

3) In either mode. If a DOS command is the first item PRIKTed 
after the GET, :he DOS command may not be executed because 
the necessary preceding RETURN is missing* 

In the program GET WDRDS2* the non-printing "throw-away" character CTRL-A 
<TS) was placed before the first desired PRINT character in line 115. 
This takes care of problems 1 and 2, above. To cure problem 3, the RETURN 
character (R$) was placed before the PRINTed DOS command In line 130, much 
as was done with TRACE (see page 44). 

When this program is RUN with HON C, I, in effect, you will ace the 
following (but all displayed in one column, not three): 
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ft 9 

Hp DO 00 

flpf DO* GOO 

flFfl WJRfl G0Q5 

HF-VLE DOtfW GOOSf 

OOWW 

& POWWT M 

»* HR 

WW € MRT 

eat***) ehol ic 

f ICl 

e icic 

C« F ICICL 

cwt » icicle 

CftTW Ff») CLOSE 

CftTHL FKUl . 

cmrmo pmnts 



CnTMLOG S 

And lastly, here's an Applesoft progran that creates a file M0RDS3, with 2 
words in the first field, 3 words in the second field, and 6 words in the 
third field. 

Id REM MHKE *0M»S3 
S M « CNR* <4>: REM CTRL-* 
m P*INT "OPtN U0ROS3- 

4«i PKtUT "MBITE MC*DS3' 

se pp.inr -*p*n_E. 

G& PKJUT "Cmm_OG> DOWWNT. EHGLE" 
70 PRINT "FffUI GOOSE/ HRT- ICICLE 

fff 

The firat field will contain 
APPLE. BANANA 

And la 13 bytes long, one per character (commas must he counted too) plus 

one for the RETURN character. The second field. 

i ATA LOG i DORMANT » EAGLE 

la 22 bytet* long; the third field, 

ntUlT .GOOSE. HAT, ICICLE 

In 23 bytes long* 
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When RUN with HON C, 1, in effect you'll see 



<*-tN iJORtflx; 

WTML'OBf f<WWNT- EttOLE 
/ ftlTl Y . GUOSC. MOT. ICICLE 

t.J-OSE WUB:053 

Here* ii a program to retrieve U0RDS3: 

IO RE« RETRIEVE MRDS3:A 
A 1 * C* • CHR» (4) REM CTRL-© 
SO PRINT Mi "OMEN M0RDS3" 
4* PRINT -REflO M0Pft>S3* 

tW INPUT T»,U«. V» 

TO INPUT Uf . X*- Y». Zt 

80 PRINT P»; "CLOSE MC«*PS3" 

W END 

When RUN with HON C, I, In effect, you'll see the following: 

OPEN WORPS3 
READ 

thpple, b*n»=m« 

"■CATALOG, &QRNONT. EWtUt 
7FRU1T- GOOSE. HAT, ICICLE 
CLOSE WORDS? 

The programs to READ the sequential text file. WORDS 1, WORDS 2, WORDS 3 were 
carefully designed to READ exactly the correct number of fields and the 
correct number of items per field- In general, a program to retrieve a 
text file must be designed around the specific file. If you make a 
mistake, the results can appear somewhat confusing- For Instance, 
consider the following "wrong" program to retrieve the words In text file 
WORDS 3. 

10 REM fit H(I EVE 
& 09 m --: REM CTRL-0 
3© PRINT P»j "WEN M0RDS3" 
40 PRINT 0», "READ MUR0S3* 
5B INPUT fi*-&* 
60 INPUT i>it 
?* INPUT K»,X», V* 
SO PRINT Ml "CLOSE MQRPS3" 
90 END 
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With HON C, I, In affect, here's what you would see on RUHning the 
program. 

OPEN MOROS3 
PEfiO MOROS3 

mruu nftMM 

KWfPLXXb OORHONT- EI^E 
?FRUJT, GOOSE, NAT, ICICLE 
1EXTRO IGNORE* 
CLOSE M0RPS3 

The INPUT command In line 70 caused the entire field containing 
FRUIT, GOOSE, HAT, ICICLE 

to be BEAD Into the Apple. The first three words were assigned to the 
variable. HS. XS and VS. But there is no variable corresponding to the 
fourth INPUT response, ICICLE, so the message 
EXTRA IGNORED 

Is displayed, and execution continues. 

Here is another "wrong" program to READ the text file WORDS 3: 

lO REM RETRIEVE M0RTS3:C 
fiW D» - REN CTRL-P 



30 


PRINT 


POj -open ua 


40 


PRINT 


C^-REOP MCM 


Si» 


INPUT 


**-• S» 


«o 


INPUT 


T*. m. v«. *$ 


TO 


INPUT 


XI. V*. 


M 


PRINT 


&«> -close m 


90 


ENO 





And here is a HON C, I, RUN of the program. 

OPEN M0ROS2 
R£«* H0RPS3 
WPLE-BONflNS 
WHLDO. CORNHNT. EOOLE 
T?TlfOtT, GOOSE. HOT. ICICLE 
rfXlM IGNORE!- 

END OF MTfl 
OREflK IN 7* 

This time, line 60 caused the field 
CATALOG , DORMANT , EAGLE 

to be READ Into the AppU. The three words are assigned to the variable. 
TS, US and VS. But line 60's INPUT command expected four responses, so 
It causes the next complete field to be READ into the Apple: 
FRUIT, GOOSE, HAT, ICICLE 

Th* first word, FRUIT, Is assigned to line 60's last variable, W$. There 
are no more variables with this INPUT command, so the message 
EXTRA IGNORED 
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is displayed, and execution continues. There are no more fields In the 
file, so line 79's INPUT command causes Che 
END OP DATA 

message, und the program cows to a atop, 

A somewhat more general pair of programs, MAKE TEXT and RETRIEVE TEXT arc 
discussed in a later section. They illustrate how to make a program more 
adaptable to different text flies- 



OPBi-MG AND CLOSE- ING SEQUENTIAL FILES 

Sequential text files should be used when information is to be retrieved 
in a linear fashion from the beginning to the end of the flic, and when 
information does not require much updating or on-going revision* For 
example, a sequential file could be uaed to contain data for a 
word -guessing game, as in the preceding sample programs* 

To create a sequential text file, the commands 

OPEN 
WRITE 
PRINT 
CLOSE 

are used, in the order shown (though not necessarily right after each 

other). To retrieve a sequential text file, the commands 

OPEN 

READ 

INPUT 

CLOSE 

are used, again in the order shown though not necessarily right after each 
other. Both procedures are illustrated in the preceding section* 

A certain ritual is required before and after you create (WRITE) a 
sequential text file: before using the file you must OPEN it. When you're 
done, you must CLOSE It. The same is true when retrieving (READing) a 

sequential text file: OPEN before READing, and CLOSE the file when you're 
done- 




Piles that have been OPENed must be CLOSEd. Failure to CLOSE a file that 
was OPENed and written to by a WRITE command may result In loss of data. 

The syntax for these commands is similar to other DOS commands. 

1 Note: OPEN and CLOSE arc also used with random-access files — see 

Chapter 8. ] 

OPEN f I, So J [,DdJ [,W) 
CLOSE [fl 

Examples: OPEN SESAME 

OPEN SHOP, D2, S7 
CLOSE 

CLOSE MOUTHED 
CLOSE WINDOW 
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OPEN sets aside workspace in the Apple for the file f (for those who know 
shout such stuff, OPEN allocates a 595-bytc file buffer to handle this 
file's input and output), and geta the system ready to read or write from 
the beg innin g of the file. OPEN also sets up the slot and drive numbers 
to be used by the subsequent WRITE (or READ) command* 

Tlie CLOSE command releases the workspace in the Apple (de-allocates the 
file buffer associated with the file f). If f is not specified, all OPEN 
files will be closed, with the exception of any file being used by the 
EXEC command. EXEC files are discussed later in Chapter 7. OPEN 
sometimes CLOSEs too: OPEN first checks to see if the named file is 
already OPEN; if so, it CLOSES it before re-OPENlng it. 

Note that the CLOSE command has no Drive or Slot parameters. If you type 
CLOSE MYFILE 

then any file named MYFILE will be CLOSEd, regardless of the slot and 
drive number associated with the file- Similarly, the command 

CLOSE 

will CLOSE all files (except a file being EXECed) on all disk drives* 
In various circumstances, you may wish to delete a file f that may or may 
not exist* This is especially important to avoid problems of overwriting 
an old file (unless you overwrite the entire old file, part of the old 
file will remain, attached to the end of your new file). Suppose a game 
creates and uses the file 5CORES each time it is played, and you wish your 
program to delete any old file by that name at the start of each new game. 

The command 
DELETE SCORES 

will cause the error message 
KILE NOT FOUND 

if the file doesn't exist, and your program will halt. Here's a quick way 
to delete any file named SCORES and re-OPEN it for new data, whether or 
not that file already exists: 

5 rem PEiereR 

15 PR1MT t>*\ "OPEN SCORES" 
2fc PRINT D*; *DELE7H SCORES'* 
23 WIMT Wi "OPEN SCORES* 
Jft REM 

WCnftrMDCR OF PROCTWH 



WRITHING SEQUENTIAL FILES 

Here is another program which creates a sequential text file* This 
Applesoft program creates a text file named SAMPLE which contains 3 
strlnga and 10 numbers- 

The file SAMPLE may or may not already exist each time the program is RUN: 
If it does exist, it should be DElETEd so as to remove old data from the 
file. If it doea not exist and your program tries to DELETE it, you'll 
receive the message 
FILE HOT POUND 



59 



nnd the program will stop. Lines 20 and 30 take care of the problem If 
SAMPLE already exists, line 20 OPENs tt and line 30 DELETES It- If SAHNX 
does not exist, line 2d creates a file SAMPLE and line 30 DELETES it. 
When line 40 is executed it creates a clean new file SAMPLE* so the 
problem uf mixed files Is avoided. 



lei 


M ■ CMKf <4i REH Cm. 


fc* 




p^iht 


M- "OPEN SWIPLE" 




30 


PRINT 


(Wi 'DELETE S*HPL£' 




4*» 


PUNT 


Ml. "OPEN SJWVE" 




9*f 


PR IM- 


0*. "WRITE SAMPLE" 




t* 


PRINT 


"HI MO" PR INI -HI 


M0- 


re 


PRINT 


'OPT TO THE PISK M 


: 00" 


m 


FOR J 


■ 1 TO 16 






RRWT 


i 




100 


NEXT 


3 





lift PRINT 0#> -CLOSE SWWPLC- 
END 

Here's what you see on the screen when you RUN this program, if HON C, I. 
is in effect. 

OPEN shhrle 
DELETE S**nPi_£ 
OPEN S**NPLE 
WITE SfWLE 
*iJ HO 
MI HO 

OPF TO THE OISK ME 00 
1 

if 

3 
4 

6 
7 
P 
9 
10 

CLOSE SAMPLE 



Before you WRITE a file. It wist be OPENed; CLOSE it (quietly, please) 
when you're done. Both the OPEN and WRITE commands must refer to the same 
file name . 

Once a WRITE command is executed, any subsequent PRINT commands send all 
characters to the diskette, instead of the screen. A WRITE command is 
cancelled by the use of any DOS command in a PRINT statement. Even the 
"empty" DOS command (just CTRL-O) will do. 
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An INPirT command of the form INPUT X$ also cancels a WRITE cownand, but 
only after storing as the last text file character the ? which the INPUT 
comuiiid normally displays on the screen. If the forn 
INPUT "WHAT'S YOUR NAME? "; XS 

is used, the WHITE Is canceled after the characters lo the string are sent 
to the diskette* 

© 

An error message cancels a WRITE command, but only after the entire error 
message is stored as the last field In your text file. 

The syntax for the WRITE command when used with sequential files iax 
WRITE f 

[Note: WRITE la also used with random-access files, sea Chapter 8.] 

Examples: WRITE LETTER 
WRITE RIGHT 

The sample program given at the beginning of this section is a simple 
Illustration of the moat basic (BASIC?) elements needed to create a text 
file, A slightly more general Applesoft program called MAKE TEXT is on the 
System Master diskette that cane with your dlak drive. 

HAKE TEXT allows you to create a sequential text file containing up to 100 
strings; each string may have at moat 239 characters. Try it — you'll 
like It (we hope). Place the System Maater diskette in your drive and 
type 

LOAD MAKE TEXT 

A LISTing of the program should look like this: 

5 RE" 'IRkC TEXT 

20 D# * CHR« t4> : REM CTRL P 
2& M« . TEXT 

00 PRINT "VOU GET TO TYPE ONt ST 

».im fti ft time. p 

PRINT "A STRIH3 f«V HftVE If T 
£33 CMHRRCTERS " 
60 PftUfT "THIS PfiOGRftN LETS VOL' 

MfflTE TEXT FILES 
*3 PRINT .1 # 1 ♦ % 
IS* PRINT "t'PRESS TrC ft£Tt*N KtV 

TO QUIT. > 
tf* PftlNT "TYPE STRING 0*1 1/*' *■ 

( Continued on next page ) 
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(Continued Iron previous page) 



fa 



protected. (This step Is necessary because this program, like the ANIMAI-5 
program discussed In Chapter 4, creates a nev file*) 



YOU GET TO TYPE ONE STRIMQ AT fl TIMS 
ft STRING mv H»V£ UP TO 229 CHflffflCTEfi!>. 
THIS PROGRl 1 *: LETS V0L1 WRITE TEXT FILES 



CPRESS THE RETURN KEY TO fJUJT. > 
TYRE STRING •! ■ 



Once the program is LOADed, SAVE it on a diskette that's not write- mff 1 





■ 


















. ■ 


mm 




■ ».> «Qp«w -j 


m 






*. 










RRiNt "WRITE 






pftTW* r - i 






.* = l TO 1 - 


t 




PRINT fl*tX> 












PP!«T Mb -'CLOSE 


' i N* 



Is MAKE TEXT still in your Apple? And a non-wri tc~prot*cted diskette in the 



drive? If so, type |S~ i 3 

HON C, I t 

so you can see the coounds sent to and fro* the disk- Then type RUN 
and you should see the following message: 



± 



4. 

Type in as many strings as you like (up to 100 may be entered)* Warning | 
the program uses INPUT, so don't typo commas or colons Into your strings. 0K 1 ^3 

When you vish to quit, just press the RETURN key instead of typing a 
string. You'll be asked 
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Choose a name for your text file* press the RETURN key* and as your strings 
are seat to the disk you'll see them printed on the screen* First will 
appear the disk commands Spt 1 

OPEN f ^ 
DELETE f j I _ 

open f m 1 

WRITE f 

(where the f is replaced by the file name you chose). They'll be followed by ^C_ t JJm 
a number -- the number of strings you entered into the file* (This 1 
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nnmliiT will ho used by a program discussed in the next section that 
retrieves your rile). Ne*t you'll see your strings. Finally you'll see 

(he r:i. ■■■■ m'.> 
CI.OSR f 

Here's s sample HUN of the MAKE TEXT program: 

THIS LETS YOU WRITE TEXT FILES 

wu get ro tvpe one string m n time 

ft STRING H*4V MRV£ UP TO 23? CN**0*CT£RS. 



<TO OUIT PRESS RETURN KEY FIR$T> 
tYPE STRING RA. KCRE-S STRING 1 

<TG SUIT. PRESS WTWW KEY FIRST? 
TYPE STRING R2 NNP MY SECOND STRrwO 

<TO BUIT, PRESS RETURN KEY FIRST > 
TYPE STRING *3: ON WE GO 

(TO 9UIT- PRESS RETURN KEY FIRST' 
TYPE STRING M ENOUGH ftLPEfiOY' 

CTO OOJT, PRESS RETURN hEV FIRST > 
TYPE STRING R5 

isHRT FILE NBMC? TEST 

OPEN TEST 

DELETE TEST 

OPEN TEST 

MRITE TEST 

« 

HERE'S STRING 1 
**€' NY SECONO STRING 
ON ME GO 
ENCWGH ALREADY-' 
CLOSE TEST 



If you OPEN a text file that already exists ond then WRITE to it (without 
first DELETEing the file and rc-OPENing it), then you will overvrite at 
least a portion of the file. Unless you overwrite at least as many 
characters as existed In the old file* the result Is that the new file 
contents will be a mix of the data PfUNTcd to the file on the two 
occasion*. First will appear the new characters you PRINTed to the file 
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this time, and then will follow any portion of the old file you did not 
overwrite. To clear all characters from the old file* OPEN and DELETE the 
old file before you OPEN it anew* (In the program MAKE TEXT, 1 ines UK 
and 159 take care of "cleaning out" any previous text file by the same 
name.) To keep programs from overwriting a flic. LOCK the file. 



READ-MG SEQUENTIAL Hlf S 

The DOS command READ allows you to retrieve a text file. Once a READ is 
executed » any subsequent INPUT statements (or GETs in Applesoft) refer to 
the specified file instead of the Apple's keyboard* This Applesoft 
program retrieves the text file SAMPLE created by the program listed at 
the beginning of the preceding section. READ* like WRITE, must be 
preceded by OPENing the file to be used- The file must be CLOSEd as well. 

3 REM MCTKJEVE SAMPLE 

i* M ~ ONM <4>: Ken C«R*<4> 

is ct*h,^> 



2» 


pwjui 


P*< "OPEN SWPUE" 


*e 


WJNT 






IWIT 






FOR I 


- i to ie 


<« 


IMPUT 


u 


79 




i 


f.Ct 


pkimt 


D9t "CLOSE SflNPtE" 



An OPEN must precede a READ, and an INPUT (or, in Applesoft, a GET) must 
follow a READ. The OPEN and READ must refer to the sane file name. If 
you RUN the program with HON C, X, in effect you'll sec this: 



•MX HO 
r?HI NO 

rW TO THE OJSK HE GO 

1 

ft 
72 

to 
?s 

?6 
17 
It 

?io 

CLOSE SWHFVE 

The program was written explicitly with the SAMPLE file in mind: it 
assumes that the text file contains 3 strings, (AS. B5, and C$ in line 40) 
and 10 Integers (U in line 60). Two question marks are printed when BS 
and CS are INPUT because RETURNS separated the INPUT's multiple responses. 
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A KKAD romnuind is cancelled by the use of any DOS command in a PRINT 
statement' The "empty" DOS command (just CTRL-D) will do Just fine. Use 
of the PR# or IHt commands also cancels a READ. 

The nyntax for the READ command is the same as for WHITE: 
READ f 

[Note: READ is also used with random-access files, aee Chapter 8. J 

Examples: READ LETTER 

READ CAREFULLY 

s 

Stopping a READ in Applesoft using CTRL-C will generate a string of 
REENTERS. To avoid this, press the RESET key to stop the program. 

An Applesoft program that retrieves teat files created by the MAKE TEXT 
program is on the System Master diskette* Place the System Master diskette 
In your drive and type 
LOAD RETRIEVE TEXT 

then SAVE the program on the same diskette you used for MAKE TEXT- (The 
program is really a companion piece to HAKE TEXT, and It's simply more 
convenient to hove them on the same diskette*) 

A LISTing of the program should nppear as follows: 



12 PRINT "THIS PflOOWl WTPtEVES 
14 PIT PIT "CSEftTCCV DV THE P £W)TO 
16 WtlNT "HON C* LO IS IN EFFECT 
18 PRINT 
* 

22 PRINT l>»- "HON C, 1,0* 
£4 PPiNT 
30 PRINT "OPEN 
10 PRINT ". T* 

INPUT I 

99 oin PWfl? 

<f0 FOR J - I TO I 

rm input «t'.j> 

&0 NO T J 

90 P*1nT (y*. -close zt 
tee f*int cw> -nohon c, 1-0- 
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Now type 
HUN 

and you should see the tnensnge 

THIS- PWOGWM *£T*fIEACS TEXT FILES 
CMMTCD BY THE HRKC TEXT PKOGRflri 
C 1.0 IS IN EFFECT 

MRVC OF TEXT FILE* 

Type in the name of the text file you created using the MAKE TE3CT program, 
press the RETURN key, and you should be off and running (oops — rather, 
READlng). 

Here's what you'll see if the file TEST, used aa a saaple at the end of 
the last section, is retrieved using the RETRIEVE TEXT program: 

THIS PKOORHH «ETRf£\tS TEXT FILES 
OOTID PV THE 'MAKE TEXT * PffOGRflTl 
HOW O 1,0 IS IN EFFECT. 

WHE OF TEXT FILE' TEST 

CF-EH TEST 
W«0 TEST 
74 

THERE'S ST»IHQ 1 
?HND MY SECOND STRING 

ME GO 
?EM0U3H HLREflDV' 
CLOSE TEST 
NOHON C, 1.0 



MORE ON SEQUBJTIAL FILES: APPB4D AND POSITION 

The DOS commands APPEND and POSITION, respectively, allow you to add text 
to the end of a sequential text file, and to access information fro* any 
specified field within a text flic. 

APPEND allows you to add data to the end of a sequential text file* 
This is particularly useful if you wish to extend the information in a 
sequential text file* as in the ANIMALS program discussed in Chapter 4 
could have- The command OPEN, you will recall* always sets the 
posit ion-in-the-file pointer to byte 9 y the first character in the file* 

The command APPEND performs nn OPEN for you on a file that already 
exists, then sets the posi tion-in-the-f ile pointer to one byte beyond the 
last character in the file. 

The following program builds a file called TESTER that contains the two 
strings "TEST fl" and "TEST Vi 
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£ Witt wn TE&TER 

!» P« » CHfr* H> CTRL-* 

*W **INT (*> "OPEN TESTER" 

S9 PRINT P*. -fcCLCTE TESTER* 

4* PRINT O** "OPEN TESTER" 

» PRINT WRITE TESTER* 

» PRINT "TEST 9" 

TO PRINT •TEST I" 

9* PRINT MU "CLOSE TESTER* 
The following program APPENDS the strings "TEST 2", "TEST 3 rt and 'TEST 4'* 
to the file TESTER: 

5 REN flPt*EW> TESTER 
MM - CHPW C4>; ITEM CTRL-© 
X PS INT t>#> "flPPENO TESTER" 
3© PRINT Mj "WRITE TESTER" 

4o wtnm "TEST 2* 

7*> PRINT " TEST 3* 
&* PRINT "TEST 4" 
79 PRINT 0*j "CLOSE TE5TER- 

The following program displays the file TESTER: 

10 R£N RETRIEVE TESTER 

-» M * CMR* <#> REM CTRt-D 

30 PRINT W "OPEN TESTER* 

4C PRINT M; -READ TESTER" 

» FOR 1 * 1 TO 5 

tB IWTJT fit 

re next i 

SO PRINT M* "CLOSE TESTER* 

APPEND must be followed by WRITE (attempting to READ will just cause the 
END OF DATA message). The syntax for the APPEND command is doubtless 
familiar if you've been reading straight through this manual: 
APPEND f [.Sal [,Dd] i.Vvl 

APPEND, even though it is used only for WRITEing into a text file, does 
not cause the 
FILE LOCKED 

message if the file is locked- That message is given only if you attempt 
to actually WRITE to the file* 

The DOS command POSITION allows you to WRITE or READ information beginning 
in any given field of a sequential text file- The syntax for the POSITION 
command is 
POSITION f I.Rpl 

where Rp is the Rclative-f ield position. This command specifies that 
DOS'* posit ion-in-the-f ile pointer will be moved forward (only) to the 
p-th field ahead of the current pointer position- If p 3 9* the following 
RKAD or WRITE begins In the current field- If p-1 , the following READ or 
WRITE skips the current field and begins In the nest field- If p-Z, the 
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following READ or WRITE skips two fields including the current field, 
before beginning to READ or WRITE. And so on. If your file does not 
contain any field corresponding to the relative-field position specified 
by the POSITION command, the message 
END OF DATA 

will be displayed, and program execution will stop* 

POSITION with the Rp parameter specifies a relative field position, p 
fields ahead of the current field* POSITION must refer to a file that you 
have already OPENed, OPEN automatically sets the position-in-the-f lie 
pointer back to the beginning of the first field. Thus, if POSITION is 
used Immediately after OPEN, the relative^ ield position also 

corresponds to the actual , or absolute, field position- In no other 
case is this true- 
Like any other DOS command, POSITION cancels a READ or a WRITE* Therefore 
POSITION must be used before the associated READ or WRITE. 

POSITON actually scans the contents of the file, byte by byte, looking for 
the Rp-th RETURN character. If, during this process, it encounters an 
"empty" fvalue 9) byte, the message 
END OF DATA 

Is presented immediately . It Is not necessary to actually INPUT or GET 
any such null character- 
Here is a program that uses POSITION to retrieve various fields from the 
TESTER file, created earlier by the MAKE TESTER and APPEND TESTER 

programs: 

I» *£ft POSITION TESTE* 

28 Pf * CHM 14>: «CM CT»4,~C> 

» PRINT D»; "OPEN TESTER-- 

40 PRI«T "POSITION TESTER- Jt2* 

S* *tf INT M» *KERC> TESTER* 
60 INPUT M 

79 PRINT [**> 'POSITION TE5TC*Mtl* 
8* PfttHl ft* **Eftt> TESTER" 
99 INPUT e* 

J«W F*INT 09, "OPEN TESTER" 

Um PRINT «*J "POSITION TEStfcRrRJ 

120 PRINT D». -RCflP TESTE*" 

539 INPUT C* 

140 INPUT ES 

190 F*IN7 09. "CLOSC TESTER" 

If you HUN this program with HON C, I, In effect, you will see: 

OPEN TESTES 
POSiriOM TESTER, R2 
tK00 TESTER 
''TEST J 

POSITION TESTER- Rl 
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1ES1 * 
UWN TESTE* 

PWS I T ITJN TESTER'.' R> 

«;«!> TESftR 

TEST 3 

TEST 4 

Ci.051: TESTER 

Are you surprised at the results? Remember that the current field is 
relative-field position number 9. AIbo, remember that each IHPUT causes 

one field to be READ into the Apple, and advances the 

position— in-the-Eile pointer to the beginning of the next field* 



BYTE- IN G OFF MORE 

Note: the following section is not for beginners, and sequential files 
can be used perfectly well without a knowledge of the parameters discussed 
here. 

The DOS commands WRITE and READ can be used with a Byte parameter to 
WRITE or READ Information starting from any place In a text file — jX 
you know where that place is- The trick Involves knowing at exactly which 
byte In the file you want to start (each byte contains one character's 
ASCII code). To do this* you must know exactly how you have stored 
information into the flic* You mist count all RETURNS, commas, spaces and 
other characters in the file when figuring out where to begin. The 
problem is even more difficult for WRITE, because you oust also know where 
to end. 

The B parameter is an actual or absolute position in the file unless R is 
specified. If R is given, the B parameter is the actual position within 
the specified field. 

The command 

WRITE THISHONTH. B27 

sets the position-in-the-f lie pointer to the twenty-eighth byte of the 
file named THISHONTH <the first byte Is number 0}. Characters sent to the 
disk by a subsequent PRINT command will replace an equal number of 
characters that already existed in the file, beginning with the character 
in the 28th byte. 

This over-vriting is not confined to the current field. If you PRINT 
fewer than the number of characters remaining in the current field, you 
will create two new fields: the field you just PRINTcd, followed by the 
tail-end of the field you were over-writing* If you PRINT more than the 
number of characters remaining in the current field, you will over-write 
some of the characters at the start of the next field: the current field 
will then be longer, and the next field shorter than before. 
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It is oLho possible to WRITE into bytes that are beyond the last byte of 

an twisting sequential text file- An attempt to READ the intervening 
un-vritten bytes will cause the 
END OF DATA 

message to be displayed, and your program vilt stop* See the discussion 

of REAP with the B parameter, for information on accessing sequential text 
file fields that arc not next to each other* 

The syntax for this command is 
WRITE f [, fib) 

where the & parameter specifies the file byte at which characters sent by 
the next PRINT command will begin replacing file characters* The default 
value of b is 0, the first byte in a file* Byte b is an actual , or 
absolute, position within the file. The & parameter may specify a 
position either before or after the current position-in-the-f ile pointer* 
[Note: this command is also used with random-access files* See Chapter 8*1 

Similarly, the command 
READ LASTMONTH , B32 

sets the posltion-in-the-f lie pointer to the thirty-third byte of the file 
named LASTWONTH (again, the first byte is number (J). A subsequent INPUT 
command will cause all characters in the next field (l.e* up to the next 
RETURN character)* beginning with [he character whose ASCII code is stored 
In the file's 33rd byte, to be READ into the Apple. If the 33rd byte does 
not contain the first character of a field* only the remaining characters 
in that field will be READ* 

Syntax for this command is 
READ f I,Bb) 

where the B parameter specifies the file byte where the next INPUT or GET 
command will begin reading characters* The default value of b is 9, the 
first byte in a file. Byte b is an actu al,, or absolute, position within 
the file. The B parameter may specify a position either before or after 
the current positioo-in-tho-f ile pointer- I Note: this command Is also 
used with random-access files, see Chapter 8. ] 

The following program sets the position-in-the-file pointer to byte 14 
(the fifteenth byte) in file TESTER, which was created earlier by the 

program MAKE TESTER* Than it WRITE* the string "APPLE COMPUTER"* Note 
the familiar sequence: OPEN, then WRITE and PRINT, and finally CLOSE. 

5 REM BYTE £#f ITER 
1© M * Offt <4>- RfcM C**L-D 
2« PfilMT OPEN TESTER* 

39 FHIHT 0*i "tfRITE TESTER- 
4* Wihff "RPK-E COMPUTES* 
» PRINT &*i"CL05r TESTES' 

With HON C, l» in effect, RUN RETRIEVE TESTER to see how the previous 
program has changed the file TESTER. As you can see, the field containing 
APPLE COMPUTER has completely over-written the fields that cootained TEST 
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1 and TBST 4. as well as the first character ot the field that contained 
TEST As there are now only four fields lo all, the END OF DATA RUMS* 

uns displayed after the fifth INPUT command. 

The following program sets a pointer to byte 18 in the file TESTER, just 
modified by the preceding program. Then this program READs to the next 
RETURN In the file. Again the familiar formati OPEN is followed by READ, 
next come INPUT statements (or, in Applesoft, GETs may be used) and 
finally the file is CLOSEd. 

5 REM BVTE REflCCR 
IBM - CMRf <4> REM CTRL-& 
2* PRINT E>*i "OPEN TESTER" 
» PRINT E*;"REW» TESTE*. 

iWUT «# 
5B PRINT Mi "CLOSE tESTER* 

Try to predict what you will see, before you RUN this program. 
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CHAPTER 7 




t T«»t Fll«; 



EXEC 
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76 Capturing Progrtw In « Text Fil« 

7? Converting fUchln*-Laogu*g* loutlm* to U5IC 

?b MAX FILES and lnt#g«r BASIC Program* 

It ttBCutiv* SetBloB 



To bcctcr understand Che contents oE this chapter* it is suggested that 
you first read Chapter 6, on sequential text files* 

CONTROLLING THE APPLE VIA A TEXT FILE: EXEC 

The DOS command EXEC is similar to RUN, except that the disk file used by 
an EXEC command Is a text file that contains commands or program lines. 
Including BASIC statements, as If they were typed at the keyboard. 

To initiate a demonstration of some EXEC command abilities, 
LOAD EXEC DEMO 

from your System Master diskette and then SAVE it on a diskette that's not 
vrlte-protected* Leave the un~wrlte*-protected diskette in the drive, 
since the program WRITES a text file* 

Next RIW the program. You should see the message 

« PNEC CCWO » 
rMIS CREATES A SECPJEMTIHL TEXT 

FILE MANED "DO'ER* COWTOIWIMG SCVEftftL 
STPIMQS, EACH A LEOAL WPPLE II COftWO 
WHEN VOU TVPfc 
EXEC tO E» 

TfOi THE COHHANfcS IN PILE DO Ett TAKfi 
C3DNTWX OF VOU* COMPUTER EACH COAHHWP 
MILL BE EXECUTED JUST AS IF IT Hf*> BE£M 
TVPE4* AT THE WVOWW THE DOS AflNUHL 
PC SCRIBES THE PPOGRftN IN MURE DETAIL 

« HAPfV EXECUTING » 
PRESS TME SPACE ftf* TO l**E THIS 
f*CHiR«rJ C*C*T£ 7 ME FILE CO ER 

IF VOU WISH TO STOP THIS FWOQRAW NC«. 
VOL' AAV F*ESS T« ESC KEV 

Tress the Apple's space bar, and after a brief pause you should see the 
disk drive's IK USE light come on as the program writes the DO'ER file 
onto the diskette* Now type 
EXEC DO'ER 

press the RETURN key. Your Apple will begin a flolo performance based on 
the script in the DO'ER file. 

Here's a brief summary of the major things DO'ER does: 

First DO'ER Issues a MON C, X, command, so you'll be able 

to see what happens. 
Second, a three-line program is written and saved on diskette 

under the name NEW PROGRAM! I The program la then LISTed* 
Now a FOR -NEXT loop is executed to take up some time, so 

you get a chance to look at the screen before the 

activity continues. 
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Next DO'ER uses the INT command to enter Integer BASIC, 



«nJ LOADs the program COLOR DEMOS, and LIST* It. 

At this point, DO'ER uses CALL -155 to enter the Monitor and 
executes nome machine-language instructions before using 
the FP command to enter Applesoft* 
From Applesoft a MON C,I,0 command is executed, then 

NEW PROGRAM! 1 is RUN, modified, LISTed (again a FOR 
loop allows you to take a look at the screen) and SAVEd 



1 using the name EVEN MORE RECENT PROGRAM 1 1 

fi t mJ Lastly- the program SEW PROGRAM! J Is DELETEd and the CATALOG 

™* (including the new addition EVEN MORE RECENT PROGRAM i i ) 

L Is displayed. 

■t^ ^5 And you won't even have to lay a finger on the keyboard (unless your 

CATALOG haa more than 18 entries, in which case you need to press the 
space bar to see the balance of the CATALOG entries). 



«! 
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3 CREATING AN EXEC FILE 



=3 
=3 



Here's a step by step example to illustrate how to create an EXEC file 
named DOiT that contains the following commands: 
LIST 20, 50 
RUN AWAY 
CATALOG 

First create and SAVE an Applesoft program called AWAY to use in the above 
demonstration; 



Next write and SAVE the following program, called MAKE EXEC, that will 



«j n REM fWffV 

le print *flunv fiwv uijm rum by 



^ create a text file called DOIT. When you later EXEC DOIT, the coiamands 

your MAKE EXEC program has PRINTed into the DOIT text file will tell Apple 
to RUN the AWAY program for you- Notice that the commands which are 
PRINTed into the DOIT file, for later EXEClng, are not preceded by a 



I 



^ s «n m*c emec 

| 1« W - CMR« C4> : REM CHM«:4> I ; 



^ CTRL-D 

20 PRINT C* -OPEN DOIT- 

20 PRINT D*; -MRITC DOIT* 

40 PRINT "LIST 2€»- ^9" 

Wt PRINT -RUN HWV* 

6© P91HT •Cf»T«tOO" 

7« f*-INT &*' "CLOSt DOIT" 



3 

^^J*_ commnnd 



After you have HAKE EXEC and AWAY both SAVEd on a diskette, type the 
_ commnnd 

3 BON HAKE EXEC 

in create a sequential text file named DOIT. 
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Type thft command 
EXEC DOIT 

to cause the commands In the file DOIT to be executed one by one, Just 06 
If they'd been typed in from the keyboard. Again, notice that the 
comnands now being EXECuted were n ot preceded by a CTRL-0 in the program 
HAKE EXEC* First lines 29 through 50 from the program currently in »emory 
(probably the program MAKE EXEC) are USTed- Then the program named 
11 AW AY" U RUN, and finally the CATALOG on the diskette la displayed. 



CAPTURING PROGRAMS M A TEXT FILE 

Here's a far more useful example of using the EXEC comnd: It allows you 
to capture program listings as text flies. Such a program can be used for 

* translatlog Integer BASIC programs into Applesoft 

* renumbering parts of programs and EXECing them anywhere 
Into another program 

* Inserting favorite subroutines Into programs from a 

subroutine file on the diskette by EXECing the file 

* "appending" one program to another 

* repairing programs that have become partially unreadable 
(you can capture the good portion in a text file, re-boot, 
then EXEC the program portion back into memory) 

The line numbers 2270 and 5130, following the LIST cowind in line 6 of 
the CAPTURE program, should be replaced by the line numbers of the program 
in memory that you wish to capture* The name of the sequential text file 
containing the listing Is LISTING. 

1 RCH CAPTURE 

2 M - t*** <4>: BCK CTBL-O 
2 PVtHT £*; -OPEN LISTING" 

4 fWINT Mi "U»IT* LISTING* 

5 POKE 33*30 

C LIST 5136 

7 PWINT Mj -CLOSE LISTING* 

ft TEXT ; 8X> 

Wc made the line numbers of this program very close together, so that you 
can add these lines to a program already in memory, or anywhere within 
your program that you have eight free line numbers. Tou could Just as 
easily put all the lines of CAPTURE above the highest numbered line in 
your program. 

CAPTURE creates a text file containing commands that are preceded by line 
numbers. When you EXEC that text file, the numbered commands will not be 
executed. Instead, Just as if you had typed those lines in from the 
keyboard, the lines are stored as a program In Apple's memory. Once 
captured in a text file, a program can be modified and then EXECed back 
lino Apple's memory. Unlike UJAD or RUN, EXEC does not delete a program 
Hint In already in memory. Using CAPTURE, you can capture a program in a 
text file from one language, then EXEC the program back into another 
language <of course, the program may not run without some chaoges — 
there's somewhat different syntax for Integer BASIC and Applesoft). You 
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can also use EXEC this way to add new lines to an existing program in 
memory. In fact, you can save a listing of CAPTURE in a text file named 
LIST SAVER, say. and then EXEC LIST SAVER any time you wanted to add the 
CAPTURE program to a program in memory* 

CONVERTING MACHINE- LANGUAGE 
ROUTINES TO BASIC 

Here's another useful program that will take a machine- language routine 

and convert It Into a BASIC program portion which POKZs the 
machine-language routine into memory. The program portion can be used as 
part of either an Applesoft or an Integer BASIC program, to put the 
machine-language routine into memory each time the BASIC program Is run. 

5 REM C«*-*t*ES WRITER 
1© D* « — REM CTRL-O 

15 PRINT M, -OPCH COC€-PC*£S- 
3© PRINT Mj "WELETE CODC-POKES" 
25 PRINT t*. "OPEN COOC-PWSS" 

79 PRINT E»»- "MRITE C0CC-P0KE5" 

49 cinemlrcer - ree# 

» FOR PLflCE - ?68 TO 7VS 

€3 COUNTER * COUNTER * 1 

TO IT COUNTER ■ 16 THEN COUNTER ■ 

1 

« IF COUNTER C > 1 THEN 12» 
« PRINT 

toe PRINT LINENUHBERi 

118 LINENUNBER - LlNEVUHK* * 1 

12© print ■ poke puke; '> pee* 

UU*£>j " ; 

139 next place 

135 PRINT 

1*9 PRINT I**: -CLOSE CTX*-PO*£S" 

i*e end 

When you use this program, the number in line iff should he changed to 
contain the line number of your BASIC program where the POKElng program 
portion is to start. The FOR loop In line 5ff should contain the starting 
and ending decimal memory locations of the machine- language routine you 
wish to convert. 

Once you've typed in the program, RUNning it will create Che te*t file 
CODE-POKES. Now use Che command 
EXEC CODE-POKES 

to place your machlnc-language-POKEing program portion into any other 
program, beginning at the line number previously specified. The program 
CODE-POKES WRITER will work with either Applesoft or Integer BASIC. 
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MAX FILES AND INTEGER BASIC PROGRAMS 



An EXEC file must be used if you wnnt Co Increase MAX FILES from inside an 
Integer BASIC program without erasing your program. Here's how* Use Che 
procedures described above to create an EXEC file, let'* call it FILE-EX- 

i . i ■■ should contain the following commands to allow for 5 files on a 
system: 

MAX FILES 5 
1-0 AD PROGRAM 
DH. 10, 20 
RUN 

The first lines of the program would be as follows; note that what appears 
as CTRL-D is created by holding down the key narked CTRL while typing the 
letter D* 

10 PRINT "CTRL-D EXEC FILE -EX" 

29 tm 

39 REM MAIN PROGRAM 

EXEC-UTIVE SESSION 

The usual syntax for the EXEC command Is 
EXEC f 

where f is the name of a sequential text file containing BASIC commands or 
program lines. Examples of this usage appear throughout the earlier 
sections of this chapter- EXEC with this syntax causes the first field of 

Mi* t to be read into the Apple as if it were being typed on the 

keyboard. When the first field's RETURN character is "typed 11 , the Apple 
attempts to execute the field's contents as a BASIC command, or enter the 
field's contents as a BASIC program line* The type of BASIC (Integer or 
Applesoft) is not changed by EXEC unless the file contains an FP or INT 
command • When execution has ceased on the first field, the second field of 
file f Is read into the Apple and treated similarly* The action comes to a 
stop when the last field of file f has been read* 

The EXEC command cannot be stopped by CTRL-C. 

Only one EXEC file can be OPEN at any one tine. If you are EXECing a file, 
and one of the commands thus executed is another EXEC command, the first 
EXEC file is ItamrdLately CLOSEd- Thereafter, it is the second EXEC 
command that Is being executed* 

If a file being EXECed contains a command to RUN any program, EXEC will 

wait patiently until the program ends- Then the next EXFC file command 
will be executed. 
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e> 

However, If a program is RUNning while an EXEC file is OPEN, any INPUT 
ataiitiK'ht in the program will take the next field in the file being EXECed 
us its response* ignoring the keyboard. Worse yet. if that response Is an 
immediate-execution DOS command, the command will be executed before the 
program continues* Results can be very confusing. 

If you interrupt a RUNning Applesoft program by typing CTKL-C while an 
EXEC file is OPEN, the remainder of the EXEC file will usually not be 

executed. 

If any field of an EXEC file cannot be Interpreted as a valid BASIC 
command or program line, the message 
SYNTAX ERROR 

Is generated, and the next field is read into the Apple. Thus, you can 
EXEC any text file, whether or not it contains BASIC statements (first 
be sure you've SAVEd any program in memory). In HON C t I. mode, this 
can provide a crude but handy tool for quickly examining the contents of a 
text file. 

The EXEC command can also be used with the Relative-field position 
parameter, in a way that is a bit different from POSITION'S use of that 
parameter. The syntax for this use is 
EXEC f [,Rp) 

where Bp specifies that file f is to be EXEC'd starting in the p-th field 
of file £. Since EXEC always sets the poaltlon~ln-the-file pointer to the 
first character of the file, so the parameter Rp always indicates the p-th 
field relative to the file's beginnlnfl . Thus p always corresponds to 
the file's actual , or absolute, field. R0 indicates that EXECing begins 
with the file's first field. Rl indicates EXECing begins with the second 
field, etc. 

Note that this is different from POSITION'S use of the R parameter, 

where R3 is a relat ive field only, and may indicate different actual 
file fields at different times In a program. 




EXEC MYFILE, Rf 
generates an 
END OF DATA 

message if the R parameter specifies the second field beyond the file's 
end. (If the first field beyond the file's end is specified, nothing 
happens)* 
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For * better understanding of the infonnntioo presented to this chapter. 
It Ifi suggested tn at you first read Chapter 6, on Sequential files- 

RANDOM-ACCESS HUES: HOW THEY WORK 

BjindofP-acceiiB text files are like * collection of equal-sited cells in a 
honeycomb — aoae cell* nay be full, others may be empty. Each cx&XjM 
called a record * When you create a random-access file, you must specify 
the standard site for the records the file Is to contain* 

Unlike the fields in sequential files, which may be of almost any length, 
the records in a random-access file are of specified fixed length. The 
first time you WRITE to any particular record in a file, enough space is 
set aside on the diskette for a complete, standard-length record, whether 
or not the record is actually filled- So random-access files don't 
necessarily represent an efficient use of space. However, since these 
files are set up in such a regular fashion, it's fast and easy to retrieve 
or modify information from any part of the file — hence the name 
"random-access" file. 

Random-access files should be used in applications requiring fast access 
to various parts of the file, or where individual pieces of information In 
the file need to be changed fairly often. For example, a random-access 
file is particularly suitable for maintaining a mailing list. 

Random-access files are created and retrieved in a manner very similar to 
that used for sequential files. The main difference is that certain 
commands have additional parameters: OPEN requires an L (Length of record) 
parameter, while READ and WRITE each use an R (Record number) parameter. 
Some sample programs will be presented and discussed before getting into 
details on creating and retrieving random-access files and how the new 
parameters work. More technical information about random-access text 
files may be found In Appendix C* 



A SPECIFIC RECORD 

How can you access a specific record In a random-access file? The 
following P*ir of Applesoft programs Illustrate* how DOS allows you to do 
thia. The first program requests a name <B5). a telephone number (PS) and 
a zip code (29), then sends them to record 1 of a file called MAILER : 

10 REN MAKE MAILER 

:*» c>» - chr* ' 4> **M ctrl-o 

» INPUT "NAME: *** 

40 ]NPUT -PHONE: "> P* 

SO IWUT -ZIP CODE: "*Z* 

£0 PRINT D*. "OPEN MAILER, L200" 

7-0 PRINT f>*. -H*XTE HNILER.P1" 

00 PRINT Ht PRINT P» PRINT Z9 

90 PRINT P*. -CLOSE NAILER" 
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Line 20 place* a CTKI.-D in the variable DS, as usual. 

Litis* 10 through 50 request the information to be stored. 

Oo nut type any commas or colons in your responses. 

Lint- h0 OPENs a file called MAILER, with 200-byte long records. 

Line 70 prepares for recording information in record 1. 

Line 60 sends NS, PS and ZS to the diskette — since record 1 was 
specified In line 70, all three pieces of information 
are recorded in record 1, separated by RETURNS. 

line 90 CLOSES the file. 



WUb HON C, I, in effect, when the program is RUN you'll see: 

WW* AMY DOflKS 

* > >*0N£ <4£9> 993-1010 

ZIP CODE 95014 
OPEN MAILER L200 
URITE NAIL£R< Rl 
ANY CONKS 

<425> 559-1010 

49B14 

CLOSE NAILER 

Record 1 of the file MAILER can be retrieved by this program: 

10 REM RETRIEVE NAILER; A 

20 D* « CMR» <4> : REM CTfit_-D 

30 PRINT D#; "OPEN NAILER- LlTO" 

40 PRINT Mb "REAL- NAILER Rl" 

90 INPUT Nl* Pl«. Zl» 

70 PRINT OS- "CLOSE NAILER" 



When RUN with HON C, I, 0, you'll see the following- As usual, the pair 
of question marks Indicates an INPUT with more than one response. 

OPEN MAILER. L -Waft 
READ NAILER- Rl 
WV DORKS 
T?<429> 999-1010 
»>95014 
CLOSE NAILER 

And here is a slightly different program to retrieve record 1 of MAILER. 

10 REM RETRIEVE MAILER . B 
20 0* - " REM QUOTES CONTAIN 
CTRX.-0 

?A PRINT -OPEN NAILER, l_2O0" 

4P PRINT Mi "READ NAILER. Rl" 
HQ INPUT NIC 
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69 INPUT PI« 

!W PRINT £>** "CLOSE NBlLER" 
fcNf 



MULTIPLE RECORDS 

The program that created the random-access file MAILER wrote to a single 
record in the file, aavlng three different pieces of information separated 
by RETURNS. The next program demonstrates writing to several records: in 
particular, record numbers 12 through 15 of a random-access file called 
RA-FILE. 

5 *Ert NNKE t?ft-P lit 

U 0*> • CNR* <4> REN CTRL-O 

2* PRINT o*, -opt* ««-FIlE" 

3*1 PRINT P»; "DELETE RP(-*ILE" 

«• PRINT 0»; "OPEN RA-r~ILEr *-3«" 

3» FOR I - 12 TO 13 

«• PRINT D*; "HP I IE tm-fll_£, ft*'* I 

7» print "fm ricwcss "i r 

m NEXT I 

M PRINT "WRITE RPl-F I LE. R13" 

1M PRIMT "WIS- ' 
110 PRIMT t>»« "CLOSE Rf*-*1LE" 
Line 10 sets DS to CTRL-D. 

Lines 20 and 30 make sure RA-FILE is a new file 

Line 40 OPENS the file RA-FILE. whose records will each be 

30 bytes in length. 
Lines 50 through 80 create a loop that URITEs the information 

NAME ADDRESS 

followed by the record number, for records 12 through 15 
Note that you must specify each record In a new WRITE 
command, before having PRINT send characters to that 
record. 

Lines 90 and 100 change the information in record 13 to the 

text given in line 100's PRINT command. 
Line 110 CLOSES the random-access file RA-FILE. 

If HON C,I,0 Is in effect when the program Is RUN, you'll see the 
following: 

OPEN R*)~FILE 

DELETE RW-FILE 

OPEN RW-EILE* L3» 

MRITE Rft-FIlf- R12 

NNME flPMESS 12 
WRITE RPV- F 1LE. R13 
f#'** f*"<C<RE3S 13 
•KITE R#*-F1LE. R14 
NfiME «-C*E£S 14 
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NRUt RfVf H.E R15 

nhnx mwtxss 13 

**VITE »H-fHt. R13 
CLO.t£ Rft-FILfc 

In a similar fashion, you can READ information from a selected record or 
records of a text file. The next program retrieves records 12 through 15 
□f the file called RA-FILE, trying, on line 60, to find which record(s) 
contains the letters "DOS" as the first three characters. 

3 REM RETRIEVE RH-FILE 

10 Os = OMR* <4>: REM CT*t_-0 

Mt PRINT &9- "OPEN RO- FILEj L3»" 

20 FOR J • 12 TO IS 

40 PRINT C*- "REAP Rfl-FILE. R", J 

3© INPUT ft* 

60 IF LEFT* J> « "DOS" THEN 

PRINT -RECORT> 3, - WPS CNR 
NOED " 
70 NEXT l 
BP PRINT D»> "CLOSE 

Line 10 sets up CTRL-D in DS- 

Line 20 OPENs the text file RA-FILE, whose records are 30-bytes 
long (that's what we specified when the file was 
created In an earlier program, remember?). 

Lines 30 through 70 READ records 12 through 15 of RA-FILE. 

Note that you must specify each record in a new READ 
command, before a subsequent INPUT will read characters 
from chat record. In line 50, each record comes In from 
the disk as an ASCII string terminated by a RETURN. 
Line 60 checks the 3 leftmost characters of the INPUT 
string AS from record r, to see if the word "DOS" is 
there. If it im f the message "RECORD r WAS CHANGED • " 
Is printed and the search continues. 

Line 80 closes the file. 

Here's what you'll see when you RUN the program, if MOW C, I, is in 
effect: 

OPEN Prt-EILE. L30 

RE«T> Rft-FILE. R12 

?NF#*T PODRCSS XS 

PErK- Rft-FILE. R*3 

X»OS 

AfCflrtD 13 NHS CMWtfEC 
REAP RA-FILE.- R14 
WW1E *OD«ES£ 1* 
ftErtt' Rft-FILE- R13 
TRW *»M>R£5S IS 
CLOSE RW-FfLE 
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Notice that when the file was retrieved only records that had been written 
to were examined. If you had asked for record 8 In RA-FILE, you would 
have received the 
END OK DATA 

uK-ssfiRc. since no Information had been written to that record of the file. 

Similarly, had you tried to INPUT more than one field from any of the 
existing records you would have been given the Bame message: each of 
records 12 through 15 contains only one field- 



A DEMONSTRATION: THE RANDOM PROGRAM 

Last but by no means least, the System Master diskette contains a program 
called RANDOM that uses a random-access text file to demonstrate a small 
inventory control scheme- And by small we mean small: the program can 
handle at most 9 parts. This keeps the program simple- The Apple t of 
course, la capable of handling thousands of pares in an inventory. 

First the program copies itself and the random-access text file APPLE 
PROMS used to keep track of the inventory, then it automatically RUN* the 
program for you- You can list one or all items in the inventory. You can 
also change items, either one at a time or all at once. Here's how it 
works. Remember to press the RETURN key each time you complete a 
response- 

1) Prom the System Master. 
RUN RANDOM 

and you should see the message 

THIS t>£HONSTWtT10N WILL NOT EXECUTE ON 
> »#>JTE-«rOTECT£t> DISKETTE SUCH *S 
VOUR 005 SVSTFJ1 WSTE* 

FOR VOUR CDWEWJEWCe, WOVJSIOWS HftVC 
BEEN flROt TO COPV THIS PtfOGRWI flM> IT'S 
t**T* 70 flNOTJ** DISKETTE. 



fO VOU WISH TO £K» THIS MOM? <V OR N> V 

I£ you type W for "no" in response to the above message, 
you'll find yourself back In Applesoft* 

2) Press Y FOR "yes*\ You'll see the message 

MOW ftEWING OftTft 

Followed by the message 

INSERT AN INITIftLIZEP MSKETTE* 1>*H 
TOSS THE *ETL*N *£V TO BEGIN TftflWSFCR 

3) Remove the System Master diskette* and place a 
non-wrlte-protected diskette in the drive* then press 
the RETURN key. You'll perhaps catch a glimpse of 
the message 
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HMrN Tl* rWA*rt« DrtTB HWE BCEM 

nuv rwwsftwft^* t*c htogrw mill 

MbIN GUNNING 
and then the program will begin execution. 

4) Now you should see this: 

APPLE PROftS 



LIST 1 
CHANGE 2 
EXIT 3 

LMJXt^t NUtlBEP '. 1 - 3 > 1 

Tress 1 and you should see this message: 

WWT W*H6€R 1-9 <©*flLO ft 

5> Press 0, to get a list of all "parts" in this "inventory 
system" and you'll see 

MHME SIZE IN STOCK 



1 


PARALLEL P*IN7 


25* 


MM 


2 


COWNUNICflTIONS 


256 


1250 


3 


'NOT fiVftlLA0LE> 


25* 


f 


4 


(NOT HVfHLABL£> 


25S 


■ 


5 


01 SK BOOT 


256 


432 


£ 


STRTE MACHINE 


256 


466 


7 


SECIrtL PRINTER! 


25* 


&?& 


8 


SERIAL PRINTERS 


512 


74% 


9 


CENTRONICS 


256 


1299 



P*CS5 THE UETUflfN KEV TO CONTIWE 

When you're ready to return to the list of options, press 
the RETURN key- 

6) Try out the various program option*}* Choice 1 allows you 
to list parts by part number, one at a time, as well as 
all at once* 

Choice 2 allows you to change any or all part names and 
descriptions* For example, suppose part 3 should be 
named COSMIC GLUE, site 56, with 1234 In stock. Here's 
how to revise the entry for part 3: 

select option 2, CHANGE 

select part number 3 

the old part name is displayed, with the cursor at its 
start, to allow you to enter the new name; when you 
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press the RETURN key the cursor will move to the right 
and perform similarly for part size and quantity 
to line the currently existing natae or size or quantity 
just press the RETURN key by itself. 

Choice 3 will stop the program. 



WRITE-ING AND READ-ING RANDOM-ACCESS TEXT FILES 

When used with random-access files, the CLOSE command works exactly as it 
does with sequential files (see "OPENing and CLOSE ing Sequential Files" in 
Chapter 6). However* the syntax for OPEN has an additional parameter, the 
L parameter, which is required . 

OPEN f ,Lj U5sl t,Dd] t^VvJ 

The "L" stands for "Length-of-record"; the number j indicates how many 
bytes (characters and digits) are to be allotted to each record In the 
randoa-access file you're creating (or. If you're retrieving a file, the 
number that were allotted when the file was created). II the L option is 
omitted, j is assigned the default value of 1. The number j oust be In 
the range 1 through 32767. 




When you OPEN a file prior to READing , if you specify a different Length 
parameter, than you specified when you OPENed prior to WRITEing the 
file, DOS will blindly use the new Length parameter to calculate record 
positions within the file. You will have to keep detailed written 
documentation on the structure and contents of your files (some 
programmers keep such information in record of the file). It's helpful 
to always Include the Length parameter in each file's name , with such 
names as 
RANDFILES:L20 
STOCKL I STS-L 1 00 
DIRECTORIES (L50) 

There is no way to find the length of a record in a randoe-acccss file: 
yo u must make this information part of your documentation. 

$ 

Records should never be longer than the number of bytes specified by the L 
parameter: records may be partially over-written or combined with 
confusing results. 

WRITE and READ each have an R parameter, to be used when creating or 
retrieving particular records In random-access files* 

WRITE f [,Rr] 
READ f (,Rr] 

Examples: WRITE LEGIBLY. R3, 
READ FAST, R13 
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The Kr (Record) parameter Is used to create (with WRITE) or retrieve 
(with READ) the rth record of the file. The default value of r is 0, 
specifying the first record of a file. 



Ifalng CTRL-C to stop a READ in Applesoft causes a string of REENTERS to be 
generated; press the RESET key instead. 

In some respects, each separate record in a random-access text file may be 
t rented as a short sequential file. WRITE and READ can be used with a 
Byte parameter lit addition to their R parameter. The Byte parameter 
specifies the beginning byte of the specified record, for the next PRINT 
(after WRITE) or INPUT or GET (after READ). 

WRITE f [,Rr] |,Bb] 
READ f l,Rr] [pBb] 

If specified, .the B (Byte) parameter causes WRITElng (or READlng) to 
begin at the b-th byte of the specified record. The default value of b is 
0, the first byte of a record. The B parameter may specify a position la 
the record cither before or after the current positlon-ln-the-f lie 
pointer. Using the B parameter necessitates a thorough, detailed, 
byte-by-byte knowledge of the contents of each record in the file. 

Once READ or WRITE has moved the position-in-thc-f lie pointer to a 
particular record, POSITION can also be used to move the pointer ahead 
(only) to further relative-field positions within the record. However, 
POSITION cancels either WRITE or READ mode (without changing the 
posttlon-in-the-f lie pointer) , so another WRITE or READ command (this time 
with no parameter) is necessary to re-instate that mode. 

Details on how information is scored on the diskette in general, and in 
random-access files in particular, may be found in Appendix C. 
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MACHINE LANGUAGE FILES 

DOS allows you to store on diskette, and retrieve from diskette, the 
information in your Apple ll's memory. You have already seen the DOS 
commands SAVE, LOAD and RUN: these commands deal with the contents of 
Apple s program memory, interpreted as commands in BASIC programs. The 
DOS commands discussed in this chapter — BSAVE, BLOAD and BRUN — perform 
similar functions, but they deal with the contents of anv. portion of 
Apple s memory, in its uninterpreted, raw binary-and-hexadeclmal form. 

The B before each of the following commands stands for a Binary file; a 
B also precedes the name of binary files in the CATALOG. ~A binary file is 
Just an exact, bit-for-bit copy of the information that was stored In a 
specified range of Apple memory locations. Those locations may have 
contained a machine-language program, binary data, or a bit-mapped 
"picture" from Apple's high-resolution graphics screen. 



BSAVE 

The BSAVE command creates a file named f and stores all the contents of a 
segment of memory. The syntax is 
BSAVE f ,Aa, Lj [,C*1 [,Dd] l,Vv] 

where as usual the S, D t and V parameters stand for slot number, drive 
number, and volume number- Note that the A and L parameters are not 
optional. 

The A parameter specifies the starting Address (in either decimal or 
hexadecimal code) of the memory portion to be stored on diskette. A 
dollar sign ( S ) must precede an address expressed in hexadecimal. If 
the A parameter is less than or greater than 65535, a 
SYNTAX ERROR 

message Is displayed. Therefore, equivalent negative addresses may not 
be used with this command. Within the range through 65535, no error 
message is generated if the A parameter specifies a starting memory 
address that does not correspond to actual. Installed memory chips. In 
practice. It is not useful to specify an A parameter greater than the 
maximum memory address In your Apple (49151 or SBFFF on a 48K system). 

The L parameter specifies the Length, in bytes, of the memory portion to 
be stored. If the L parameter is less than or greater than 65535, a 
SYNTAX ERROR 

message Is generated. If the L parameter is or in the range 32768 
through 65535, a 
RANGE ERROR 

message is generated. 32767 is the greatest number of bytes that can be 
stored in a single field on the diskette. If you wish to store more than 
32767 memory locations, use two BSAVEs. Within the range 1 through 32767, 
no error message is generated if the L parameter specifies a range of 
memory addresses, not all of which correspond to actual, installed memory 
chip. In practice, it is not useful to specify a range of memory 
addresses extending beyond the maximum memory address in your Apple (49151 
or SBFFF on a 48K system). 
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Thou** examples each create a file named PICTURE containing an Image of the 
second high-resolution graphics area of the Apple's memory. They are 
oporat lonal 1 y identical, but their starting address and length parameters 
are given in different forms* 

BSAVE PICTURE, A$A000, L$2000 

BSAVK PICTURE, A16384, L8192 

BSAVE PICTURE, A16384, L$2000 

BSAVE PICTURE, A$4000, L8I92 



BLOAD 

The BLOAD command returns the contents of a Binary file to your Apple ll's 
memory- BLOAD does not erase a BASIC program in memory, unless the data 
is BLOADed into the particular portion of memory containing your program. 

The syntax is 

BLOAD f (,Aa] [,Ss] I,Ddl [,Vv] 

where the S, D, and V parameters are as usual* If the A parameter is 
used, then the Binary file's contents replace a portion of the existing 
contents of Apple's memory, beginning at address a. If the A parameter is 
not used, the file's contents are returned to the same Apple memory 
locations whose contents were originally BSAVEd- See BSAVE for a complete 
discussion of the A parameter. 

Assume the binary file PICTURE contains a high-resolution picture. Either 
of these examples places the picture into the first high-resolution 
graphics area of the Apple's memory: 
BLOAD PICTURE, A8192 
BLOAD PICTURE, A$2000 

Either example also clobbers the RAH version of Applesoft. 

Mote ; a machine-language program may no longer be executable 

if It is moved to a memory location different than the 
one from which it was saved. 



BRUN 

The syntax of the BRUN command Is the same as for BLOAD: 
BRUN f [,Aal [,Ssl [,Dd] I.Vvl 

The Binary file f should be a machine-language program. 

First BRUN does a BLOAD. If the A parameter is given, the file's contents 
are placed into Apple's memory beginning at location a* If the A 
parameter is not used, the file's contents are returned to the same Apple 
memory locations whose contents were originally BSAVEd. See BSAVE for a 
complete discussion of the A parameter- 
After BLOADing the file, BRUN does a machine language jump (JMP) to 
location a* If the file was a machine-language program, this begins 
execution of that program* 
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THE RWTS SUBROUTINE 



Normally, user access to and from the DISK II is restricted to the use of 
DOS. However, another method of accessing the DISK II is available to 
machine language programmers. You may skip this section if you're not 
familiar with machine language. 

The DISK II can be accessed directly from machine language through the use 
of the RWTS subroutine, which is part of the DOS- The "RWTS" stands for 
"Read or Write a Track and Sector". In the following explanation, any 
numbers preceeded by S are hexadecimal numbers. 

Every diskette initialized by the DISK II drive is separated into 35 
tracks, numbered to 34. These tracks may be thought of as grooves on a 
phonograph record, except that they are not connected with each other. 
Basically, the tracks are arranged in separate concentric circles, with 
the large hole in the center of the diskette forming the common center of 
the circles. Track is on the outer edge of the diskette, while track 34 
is nearest the center. The disk drive has a "head" that acts very much 
like the needle on a record player, except that the head on the disk drive 
is magnetic. This head moves to different tracks on the diskette, where 

it either reads Information off of the diskette, or writes information 
onto the diskette. 

Each track on the diskette consists of 16 sectors. Sectors are pre-defined 
groupings on each track, that allow the user to work with single blocks of 
256 bytes, rather than with the entire 4096 bytes that fit on one track. 
The sectors within a track are individually numbered, consecutively, to 
15 around the diskette. As the diskette spins, each sector will pass 
underneath the head, at which time the head may write to or read from that 
sector. Each sector consists of two portions: the address field and the 
data field. The addres field contains Information concerning which track 
the head la on, which sector is about to spin past the head, and the 
volume number of the diskette. The data field contains an encrypted form 
of the actual 256 bytes of data which were stored on that sector. 

The "Read or Write a Track and Sector" subroutine (referred to as the RWTS 
subroutine), allows the user to write information to, or read information 
from, any track and sector on the diskette, via machine language. In order 
to use the RVTS subroutine, the user must first create an IOB 
(Input/Output control Block) table, and an accompanying "Device 
Characteristics Table". The IOB tells the RWTS subroutine which slot and 

drive number the disk drive will be in, which volume number to expect on 
the diskette, which track and sector to access, and whether to read from 
or write to the diskette. The Device Characteriatlcs Table provides some 
Information to the RWTS subroutine that is necessary to operate the Apple 
DISK IX. 

To use the RWTS subroutine, the user must set up the IOB and the Device 

Characteristics Table somewhere In memory. A "controlling subroutine" must 
be written and stored in memory. The subroutine must JSR to the starting 
nddress of the RWTS subroutine (at location S3D9). When the RVTS 
subroutine is jumped to, the A and Y registers must contain the address of 
the starting location of the IOB. The A register must contain the high 
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addresR byte, and the Y register the low address byte. The format of the 
^ IOB Is given In Table 3, at the end of this section. Table 4 gives the 

format of the Device Characteristics Table. 



4 

J 



*3 Here Is an example of how to use the RWTS subroutine. The sample IOB. 

Device Characteristics Tables, and a controlling subroutine will all be 
^ ] loaded into memory Just after location SC00. 

| The following controlling subroutine will load the A and Y registers with 

|^i the address of the starting location of the [OB, and tfien Jump to the RWTS 

subroutine. 

Bi | 3 $C00- A9 0C LDA *$0C Load A register with $0C 

SC02- A0 0A LDY #$0A Load Y register with S0A 

■g J SC04- 20 D9 03 JSR S03D9 lump to the RWTS subroutine 

^ SC07- 60 RTS 

SC08- 00 BRK 

The following IOB is one that you would use to access slot 6> drive 1, to 
write 256 bytes of memory starting at location S2000, onto track 18, 
sector 6 of the diskette: 



Lor.-it Ion 


Code 
01 


Purpose 

IOB type indicator, must be W\ 


$C0B 


60 


Slot number times 16 


$C0C 


01 


Disk drive number 


$C0D 


n 


Expected volume number 


$C0E 


12 


Track number 


$C0F 


06 


Sector number 


SClfl 


20 


Low-order byte of Device Characteristics Table 


sen 


0C 


High-order byte of Device Characteristics Table 


SC12 


00 


Low-order byte of data buffer starting address 


SC13 


20 


High-order byte of data buffer starting address 


$ci« 


00 


Unused 


SC15 


00 


Unused 


SC16 


02 


Command code, $02 - write 


SCI 7 


00 


Error Code 


SC18 


00 


Actual volume number 


SC19 


60 


Previous slot number accessed 


SCI A 


01 


Previous drive number accessed 



The following Device Characteristics Table must be Included, we'll place 
It at location SC20, just after the IOB. Locations SC10 and SCU in the 
IOB above point to the address of the Device Characteristics Table's 
starting location- 



Location 


Code 


Purpose 


SC20 


00 


Device type code (put a $00 here) 


SC21 


01 


Number of phases per track (put a $01 here) 


SC22 


EF 


Time count (put a $EF here) 


SC23 


D8 


Time count (put a $D8 here) 
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When you have loaded the I0B at $C0A, the Device Characteristics Table at 

$C20, and the controlling subroutine to load the A and V registers at $000, 

then 

C00C 

or 

< Ail. 3072 

will cause the entire routine to execute. 



TABLE 3: FORMAT OF IOB 



Byte* 
1 



IBTYPR 



1BSL0T 



Purpose 

Tells the RUTS subroutine what type of IOB this 
is. Should be a $01- No other type codes are 
currently defined* 

Must contain the number of the slot times 16, 
in which the disk drive's controller card is 
located. For example, if you want to access 
slot 16, the value $60 must be stored in this 
location* 



1BDRVN Must contain the number of the disk drive to be 
accessed — either $01 or $02. 

IBVOL The volume number of the diskette to be 

accessed must be stored here. Volume $0(1 will 
natch the volume number assigned to any 
diskette. 



1BTRK 



IBSKCT 



The number of the track (0 to 34) to be 
accessed la stored here. Must be within the 
range $00 to $22, 

The number of the sector (0 to 15) to be 
accessed is stored here- Must be within the 
range $00 to $0F- 



7&8 1BDCTP These two bytes must contain the address of the 

starting location of the Device Characteristics 
Table (see below). Byte 7 must contain the 
low-order byte of the address, and byte 8 must 
contain the high-order byte. 

9&10 1BBUFP Bytes 9 and 10 must contain the address of the 

starting location of the "data buffer". The 
data buffer is a 256-byte long section of 

memory upon wh Ich the RWTS subroutine will 
operate. If you are writing onto the diskette, 
the information in the data buffer will be 
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written onto the diskette. If you are reading 
from the diskette, the Information that comes 
off of the disk will be stored in memory at the 
location of the data buffer. 256 bytes is both 
the minim and the maximum amount of inform- 
ation that can be read or written by the RWTS 
subroutine. 

Mil 2 Unused 

13 IBCMD In this byte is stored the command code that 

tells the RUTS subroutine exactly what to do. 
The values that can be stored in byte 13 are: 
$00 — Null command. Does nothing but start 

the disk drive and position the head. 
$01 Read the entire 256 bytes stored on the 

diskette at the specified track and sector* 

and store them In memory at the location of 

the data buffer. 
$02 — Write the next 256 bytes stored in 

memory at the location of the data buffer on 

to the diskette at the specified track and 

sector. 

$0i — Format the diskette. When a diskette is 
formatted, self-synchronizing nibbles are 
written on every track and sector on the 
diskette. Because all of the diskette is 
formatted, the values in bytes 5 and 6 are 
Ignored. All of a formatted diskette is 
available for use; there is no DOS, or 
anything stored on the diskette until the 
user puts something there, 

U IBSTAT This location will contain the code number for 

any error that may be encountered during 
execution. If the RWTS subroutine returns with 
the carry flag clear, no error has occurred. 
If it returns with the carry flag set, this 
byte indicates what type of error has occurred. 
$10 — Diskette is write-protected* and cannot 

be written to. 
$20 — Volume mismatch error. The volume 

number of the diskette found was different 
than the volume specified in byte 4. 
$40 — Drive error. Something unusual is 
happening. 

$80 — Read error. The RWTS routine was, after 
48 repeated attempts, unable to read either 
the address field or the data field. If the 
data field for the specified sector has 
nsver had anything written on it, then a 
read error will result, because there is 
nothing to read. 

15 TBSHOD The volume number of the diskette that is 

actually found will be stored in this location. 
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TABLE J; fURHAT OF 10B 1 continued ] 
ByteJ Sane Purpose 



16 IOBPSN This byte muse contain the sloe number times 16 

of the sloe that was accessed most recently. 

For example. If you previously accessed a disk 
drive In slot 5, store the value $50 here* If 

there is no controller In the specified slot, 
the disk will hang. 

17 IOBPDN This byte must contain the number of the disk 

drive that was accessed most recently — a $01 
or $02. 



Table 4: FORMAT OF DEVICE CHARACTERISTICS TABLE 



Bytef Name Purpose 
1 DEVTPC Device type code, telling what type of device 

this is. A S00 should be stored In this byte 
for use with a DISK IX* 



2 PPTC A $01 should be stored here. 

3&4 MOHTC Hotor on tine count complemented, in 100 

■Icro-secood intervals. A $EF should be In 
byte 3» and a $D8 in byte for uae with a 
DISK II 
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, AND CHAINING 



1M «*i.Pt»wt I/O BoviCMi VU, rU, ttri Other Stuff 
l#t> tat«t*r bUlC OU1H 



SELECTING I/O DEVICES: IN#, PR# AND OTHER STUFF 

There arc various ways In which information can be used as input or outpu 
for your Apple computer- Very often the keyboard serves as a source of 
input. Usually the Apple uses a TV screen for output, but any accessory 
or peripheral connected to a controller in one of the seven Apple 
accessory slots can be used for input or output using the IIJ# and PRff 



Examples: 

IN' 6 obtains subsequent input from the device controlled from 
slot #6. Note: if slot 06 contains a disk controller 
card, this command will cause DOS to be booted* If no 
device is in slot 06* the system may "hang". Press the 
RESET key to recover- 

IN0 obtains subsequent input from the keyboard (not slot 00), 
instead of a peripheral device. 

PR0 1 transfers output to the device controlled from slot 01 , 
usually the printer. Note: if no device controller 
card is Installed in slot #1, the system may "hang" 
and you'll have to press the RESET key to recover. 

PR0 returns output to the TV screen (not to slot 00)* 



- 



The syntax for the commands is 

IN0 s 

or 

PR# s 

where s specifies the aloe to use. What happens depends on s: 

value of s result 

less than SYNTAX ERROR 

re-establishes usual device (for INI, input from 

the keyboard, for PRf, output to the TV screen) 

I through 7 transfers to device controlled from the specified 

slot (boots DOS if a disk controller card is in 
that slot) 

8 through 16 SYNTAX ERROR in deferred-execution mode ; 

the system hangs in immediate-execution node 

17 through 65535 RANGE ERROR 

greater than 65535 SYNTAX ERROR 



The command INff re-establishes input from the keyboard; PR# 
re-establishes output to the TV screen. 

With DOS in effect, the IN0 and PR* commands may be used in immediate 
execution mode in the usual way (see your BASIC manuals). But when they 
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are Untied by tines In a program, IN* and PRf must take the form of DOS 
comianndH mirh a» 

10 DS - "": Rm CTRL-D 

20 PRINT DJ; "PRff 1" 

10 PRINT DS; "Wl 2" 

When DOS is not in effect, the 1N0 and PR# commands set the contents of 
the Apple Monitor Input and Output registers to select the desired input 
and output devices* 

Mien DOS is in effect, the contents of the Apple Monitor Input and 
Output registers are set to select DOS, while the contents of the DOS 

Input and Output registers are set to select the desired input and output 
devices. The following paragraphs describe what happens each time a 

character leaves or enters the Apple. 

When the Apple sends an output character, the Apple Monitor Output 
register directs that character to DOS* If the character is to be sent on 
(because it is not part of a DOS command), DOS does a fast two-stage 
switch: 

1. First, DOS replaces the contents of the Apple Monitor 
Input and Output registers with the contents of the DOS 
Input and Output registers. Then it sends the character 
out to the device now selected by the contents of the 
Apple Monitor Input and Output registers. 

2. Next, DOS re-connects itself by again placing the 
pointers to DOS in the Apple Input and Output registers. 

Similarly, each time the Apple asks for an input character, the Apple 
Monitor Input register directs that request to the DOS. Once again, DOS 
does its fast two-stage switch: 

1. First, DOS replaces the contents of the Apple Monitor 
Input and Output registers with the contents of the DOS 
Input and Output registers. Then it obtains an input 
Character from the device now selected by the Apple 
Monitor Input and Output registers. 

2. Next, DOS re-connects itself by again placing the 
pointers to DOS in the Apple Input and Output registers. 

When DOS is in effect, DOS Intercepts all input characters from the input 
device before they reach Applesoft or Integer BASIC or the Monitor- That 
is why IN0 and PR0, when typed on the keyboard as immediate-execution 
commands, can be trapped and used by DOS to change the DOS Input and 
Output registers. 

Similarly, DOS Intercepts all output characters from the Apple before they 
reach the output device (but after they have affected the Apple Monitor 
Input and Output registers). That Is why IN# and PR0, if issued from 
within a program but not in PRINTed DOS commands, can disconnect DOS by 
changing the Apple Monitor Input and Output registers before the commands 
ever K*'t to DOS. Because the entire contents of the Apple Monitor Input 
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and Output registers are replaced each time DOS attempts to send or 
receive a character* DOS will usually re-connect Itself If it was not 
disconnected at both Input and Output registers simultaneously* 

© 

If you execute a PR# command from wi thin a program, with a program line 
such as 
5* PR* 1 

Chen DOS will be partially disconnected and unable to Intercept subsequent 
output* DOS Is still connected for input, and the next attempt to obtain 
any input character will cause DOS to re— connect itself for both input and 
output • 

The same situation occurs with the use of W0 inside programs when DOS is 
in effect. A program line such as 
60 INI 1 

will disconnect DOS for subsequent input* DOS is still connected for 
output, and the next attempt to send out a character (even a return or a 
prompt character) will cause DOS to re-connect Itself for both input and 
output* To avoid such conflicts and allow DOS to manage the Input and 
Output registers, issue PR* and IN* commands In Immediate-execution mode, 
or as DOS commands In program lines such as those mentioned earlier: 

10 DS - RE« CTRL-D 

20 PRINT DS; "PRJ 1" 

30 PRINT D5; "IN# 2" 

The CTRL-D character tells DOS that the following output characters are a 
DOS command « 
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TAM.K I: APPLK MONITOR INPUT AND OUTPUT REGISTERS 



Monitor Input RcgiHter: Locations 56-57 (538-539) 



When Register 
contents 
arc set by 

RESET 

CTRL-K (Note 1] 
1N'0 (Note 2] 

s CTRL-K [Note 1] 
INPs {Note 2] 

1 where s>0 ] 



To the 
value 

-741 
<SFD1B) 



49152 + s*256 
<5C8001 



DOS boot 



Then subsequent input 
comes f rota 

Monitor Input Routine 
from Apple keyboard 



Slot #s 

If slot #s contains disk 
controller, then boot DOS 



-8574 + Top of iwmti. 
(-9217E + STop of mem.) 



DOS 



Monitor Output Register: Locations 54-55 ($36-337) 



When Register 
contents 
arc set by 



To the 

value 



Then subsequent output 
ftoes to 



RESET -528 
CTRL-P INote IJ (SFDF0) 
PR*0 INote 2| 



s CTRL-P (Note 1] 
PR#s [Note 2] 

I where s>0 1 



49152 + «*256 



Monitor Output Routine 
to TV screen 



Slot Is 

If slot Is contains disk 
controller, then boot DOS 



DOS hoot 



—85 1 4 + Top of mem* 
(-S2I42 + STop of nemO 



DOS 



Note I. The commands » CTRL-K and s CTRL-P arc Honitor commands. To 

type CTRL-K (which does not appear on the TV screen)* type K while 
holding down the CTRL key. 

Note 2. When DOS Is in effect, this corerand will affect the contents of 
the Apple Monitor register only if the conwuind is issued as an instruction 
In a stored program and not In a PRINT CTRL-D instruction- 
Note 3. In addition tn the commands wntioned in Table 1* directly 
POKRIng appropriate values into the Apple Monitor register locations can 

aloo be used tn select input and output devices, or to re-connect a 
disconnected DOS* 



103 



TABLE 2: DOS INPUT AND OUTPUT REGISTERS 



DOS Input Register 



When Register 
contents 
arc set by 

DOS boot 
RESET 3D0G 
IN#0 (Note 4) 
PRINT DS; ,r INff0" 
[Note 51 



IN#s (Note 41 
PRINT DS;"IN#s M 
[Note 5] 
[ where s>0 ) 



To the 
value 

-741 
(SFD1B) 



49152 + s*256 
<$Cs00) 



Then subsequent Input 
comes from 

Monitor Input Routine 
from Apple keyboard 



Slot #s 

If slot fs contains a 
disk controller, then 
reboot DOS 



DOS Outpuc Register 



When Register 
contents 
are set by 

DOS boot 
RESET 3D0G 
PR#0 [Note 4] 
PRINT D$; M PR#0" 
[Note 5) 



PR's [Note 4] 
PRINT D$;"PR#s" 
[Note 5] 
( where s>0 ] 



To the 
value 

-528 
(SFDF0) 



Then subsequent output 



49152 + s*256 
<SCs00) 



Monitor Output Routine 
to the TV screen 



Slot #s 

If slot #s contains 
disk controller, th* 
reboot DOS 



104 



Noli- 4- WIhmi DOS is In effect, this coamand will not affect the 

COfltfnt* of Che DOS Input and Output registers If the command Is issued as 

an Instruction in a stored program and not in a PRINT CTRL-D instruction. 

If a program line such as 

120 PR#i 

Is executed, the contents of the Apple Monitor Output register will be 
*-hnnRcd, leaving DOS partially disconnected until the next Input. 

Note 5, In this command, it is assumed that the string-variable named D$ 
has bi't'n assigned the character control-^, or CTRL-D. This character, 
which docs not appear on the screen, is produced by typing D while 
holding down the CTRL key. 

Note 6. No matter what input or output device is selected by the DOS 
Input and Output registers, input can also be received from the disk and 
output can be sent to the disk. 

Note 7. In addition to the commands in Table II, directly POKEing the 
appropriate values into the DOS Input and Output register locations can 
also be used to select input and output devices- However, the specific 
memory locations of the DOS Input and Output registers change with 
different system memory sizes and with different versions of DOS. For 
this reason, a special procedure exists for changing the contents of the 
DOS Input and Output register locations. It is a two step procedure: 

a) Change the Apple Monitor Input and Output register 
locations to the values you wish the DOS Input and 
Output registers to contain. (This may be done by 
directly POKEing the Apple Monitor register locations 
or by executing IN# and PR# non-DOS instructions in a 
stored program, > 

b) CALL 1002 (from the Monitor, you would type S3EAG). 

After this CALL, DOS will be re-connected via the Apple 
Monitor registers, and the previous contents of the Apple 
Monitor Input and Output registers will appear in the DOS 
Input and Output register locations. This CALL can also 
be used to re-connect DOS any time your program needs 
to disconnect DOS for awhile. See the program on page 
151 for an example using this technique. 

Note 8. The Monitor commands s CTRL-K or s CTRL-P , when typed on the 
keyboard, are not recognized by DOS: they affect the Apple Monitor Input 
or Output registers directly. 
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INTEGER BASIC CHAIN 



Certain applications are most easily Implemented by using a series of two 

fir more programs which are LOADed and RUN sequentially. In such 

circumstances, the second program often needs to use the values of 

variables and arrays developed by the flrat program. The ususl RUN 

command erases the first program's variables and arrays when It loads the 

necond program. In Integer BASIC (but not Applesoft) the D05 command 
CHAIN allows you to load and run a second program without erasing the 

first program's variables and arrays. 

Suppose you've been using an Integer BASIC program called PART ONE- The 
G ortmand 

CHAIN PART TVO 

will load and run the Integer BASIC program called PART TWO without 

clearing the values of any variables used in the program PART ONE* The 
CHAIN command may be issued in immediate-execution mode as shown above, or 
from within the last lines of the PART ONE program as a DOS command: 

20010 D$- M "r REX CTRL-D 

20020 PRINT D5; "CHAIN PART TWO" 

The syntax for the command is familiar: 
CHAIN f |,5s] ( t Dd) I,WJ 

APPLESOFT CHAIN 

The CHAIN command works only with Integer BASIC, but If you do not need to 
pass variables, it Is easy to link Applesoft programs to load and run in 
sequence. In the first program. Just include a last line such as 
20000 PRINT CHRS(i); "RUN PART TWO" 

When this line is executed, it will start up the second program (where the 
second program is named PART TWO)* In the process, the first program and 
all its variables are erased. 



A different procedure must be used in order to load and run a series of 
Applesoft programs without erasing earlier values of variables and arrays. 
To chain in Applesoft, you will need to use the machine-language program 
called CHAIN that is on the DOS System Master diskette. 

To chain from a program called PART ONE to a program called PART TVO, you 
must have the CHAIN program on the same diskette with the program PART TWO 
(see next page for instructions). Then, simply Insert these two lines as 

the last two lines to be executed in the PART ONE program: 
20000 PRINT CHR$(4); "BLOAD CHAIN, A320" 
20010 CALL 520"PART TWO" 

The two lines may use any line numbers, but they should come one after the 

other in the program, as indicated. The first line loads the Applesoft 
chaining ability into the computer- The second line actually does the 
chaining (but see next page, for warning). 
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There must be no space in the third line between the CALL address 520 

and the following quotation mark. The CALL address must not be given in 
hexadecimal* 

If you have Applesoft on the firmware ROM card, you can copy the CHAIN 
program onto another diskette by using the FID program. (Appendix J) 

If you are using RAH Applesoft (on diskette), you can copy the CHAIN 
program onto another diskette using FID (Appendix J) or as follows. First 
place the CHAIN program into Apple's memory, with the command 
BLOAD CHAIN, A12296 

Then save it on the desired diskette, with the command 
BSAVE CHAIN, A12296, L456 

Note that neither Address parameter for copying CHAIN is the same as the 
Address parameter for actually using CHAIN* 
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Unless otherwise indicated* DOS conmands may be used either In 
immediate-execution mode or in deferred-execution a>ode (within a program). 
However, soiae text file coramands (e,«. READ and WRITE) nust be used in 
deferred-execution mode. 



Host DOS commands refer to a named file. A file may be a text (data) 

til*, or a program in Integer BASIC, APPLESOFT or Machine Language. The 

tables below indicate which file types nay be used by each command. The 

first table lists the commands alphabetically; the second table groups 

the« by associated file type. The commands CATALOG , FP, INT, MAXFILES, 

HON, NOMON, PRfl and IN# are not included because they do not explicitly 
refer to naoed files* 



FILE TYPE USE, LISTED BY DOS COMMAND 



DOS 


Integer 


Applesoft 


Sequential 


Random 


Hachine 


Command 


BASIC 


BASIC 


Access 


Access 


Language 


Uses 


Program 


Program 


Text 


Text 


Binary 


Files: 


File 


File 


FOe 


File 


File 


APPEND 

BLOAD 

BRUN 






x 




X 


BSAVE 










x 

X 


CHAIN 


X 










CLOSE 






x 


x 




DELETE 


X 


x 


X 


X 


X 


EXEC 






x 






INIT 


x 


X 








! OAD 


x 


X 








LOCK 


x 


x 


X 


X 


X 


OPEN 






X 


x 




POSITION 






X 






READ 






x 






RENAME 


X 


x 


x 


X 


X 


RUN 


X 


X 








SAVE 


X 


X 








UNLOCK 


X 


x 


x 


X 


X 


VERIFY 


x 


X 


X 


X 


x 


WRITE 






X 


X 





Mote: use these commands only in deferred execution mode: 
APPEND, OPEN, POSITION, READ, WRITE 
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FILE TYPE USE, LISTED BY FILE TYPE 

B * SIC filg » gai 



int eger BASIC or APPLESOFT files 
INIT 
LOAD 



KUN 



Sequential Text files only 

APPEND 

EXEC 

POSITION 



Either Sequential Text Files or Random-Ar c ess Text Fll, 

OPEN 

CLOSE 

READ 

WRITE 



Hachine Language files only 
BLOAD 
BRUN 
BSAVE 



All Types of Files 

DELETE 

LOCK 

UNLOCK 

RENAME 

VERIFY 



Note: these commands must be used in deferred-execution mode: 
APPEND, OPEN, POSITION, READ, WRITE 
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When DOS detects an error connected with disk usage, ft normally displays 
;» meHwagc describing the error and stops any program that Is running* 
These messages ore In addition to the usual messages generated by 
Applesoft or Integer BASIC. DOS messages can be distinguished from those 
of Applesoft or Integer BASIC as follows: 

An Applesoft message, such as 
7SYKTAX ERROR 

is preceded by a question mark. 

An Integer BASIC message, such as 
*** SYNTAX ERR 

is preceded by three asterisks. 

A DOS message, such as 
SYNTAX ERROR 

is preceded by no character at all. 

A DOS message appears exactly the same, whether you are In Applesoft, 
Integer BASIC or the Monitor at the time the message is generated. 

If a DOS message occurs when you are using the Monitor, the system Is 
reset to the type of 6A51C from which you entered the Monitor. 

By using Applesoft's ONERR GOTO command <see the Applesoft manual), you 
can create Applesoft error-handling routines that deal with DOS messages 
which would normally interrupt your program. When a DOS error occurs 
following an OS ERR GOTO command in an Applesoft program, a code number for 
the type of error Is stored In decimal memory location 222. This is the 
same memory location in which Applesoft stores the code for an Applesoft 
error message* The command 
Y * PEEK(222) 

sets the value of Y to the Applesoft ONERR GOTO code corresponding to the 
error that caused an Applesoft ONERR GOTO Jump to occur. 

DOS messages and their corresponding Applesoft ONERR GOTO codes are shown 
below, with the most common cause of each message. Each of the messages 
is then discussed in greater detail, with a more comprehensive list of 
causes and cures. 

ONERR GOTO CODES 



code 


DOS message 


Most common cause 


1 


LANGUAGE NOT AVAILABLE 


Applesoft not on diskette 


2.3 


RANGE ERROR 


Command parameter too large 


4 


WRITE PROTECTED 


Wrlte-protect tab on diskette 


5 


END OF DATA 


READIng beyond end of text file 


6 


FILE NOT FOUND 


File misspelled, or not on diskette 


7 


VOLUME MISMATCH 


Wrong Volume parameter 
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"NFHH COTO 



(■ illfll 

t IIUI 




Most common cause 


H 


r fi\ Ktiimu 


uoor open, or diskette not INlTed 


■ 

r 


t\ t C V till l 

Ulhh FULL 


Too many files on diskette 


■ w 


K M E 1 OrKFD 


^ e ^ l to overwrite a LULKea iiLe 


II 


SYNTAX ERROR 


Bad file name, parameter* or comma 


12 


NO BUFFERS AVAILABLE 


Too many text files OPEN 


13 


FILE TYPE MISMATCH 


Diskette file doesn't match command 


14 


PROGRAM TOO LARGE 


Insufficient Apple memory available 


IS 


NOT DIRECT COMMAND 


Command must be In a program 



DISCUSSION 

LANGUAGE NOT AVAILABLE (ONERR GOTO code - I) 

Occurs If DOS cannot find a programming language, either Integer BASIC or 
Applesoft, that Is required to execute a DOS command. The commands FP, 
INT, LOAD and RUN may all initiate a language search. If Integer BASIC is 
requested, DOS looks for that language in ROM* If Applesoft is requested, 
DOS first looks for the language in ROM, using Applesoft from an Applesoft 
firmware ROM card (if available) regardless of the card's switch 
position. If Applesoft is not found In ROM, DOS looks on the diskette in 
the "default" disk drive — the drive indicated by the default or moat 
recent values of the S and D parameters. DOS will not look on any other 
disk drive. 

This message usually arises after a DOS request for diskette Applesoft, If 
the diskette in the default drive does not contain the program APPLESOFT* 
Replace the diskette with one that containa the program APPLE50FT; or use 
the D parameter with any DOS command, to select the another drive. A 
command such as this will do nicely: 
FP, D2 

If you think DOS should have found Integer BASIC in ROM, but it didn't* 
try the following; 

I* Turn off your Apple and remove the cover. 

2. Locate the row of four large ROM chips (black, rectangular 

objects) in the middle of the main prlnted-circuit board. These 
chips are labeled "ROM F8", "ROM F0", "ROM E8" and "ROM E0". 

3- Press down firmly on these chips. 

4. Replace the cover, turn on the Apple and try INT again. 

If you think DOS should have found Applesoft on your firmware ROM card, 
but It didn't, try the following: 

? ur _P off your Apple and remove the cover. 

2. Unplug the Applesoft firmware ROM card. Locate the row of 
five large ROM chips (black, rectangular objects) across the 
card. These chips are labeled I, 2, 3, 4, and 5 above 

the chips, and Dfl, D8, E0, E5 and F0 below the chips. 

3. Press these chips firmly Into their sockets. 

4. Plug the Applesoft card back into slot #0, the leftmost slot. 

5. Replace the cover, turn on the Apple and try FP again* 



115 



RANGE ERROR (ON ERR GOTO code - 2 or 3) 

Occurs when the value of a DOS command parameter or a DOS command quantity 
is too large or too snail* Refer to the manual to see which DOS commands 
are used with which parameters- 
Range 





Parameter 


Letter 


Minimum 


Maximum 


All Files: 


Slot 

Drive 

Volume 


S 
D 
V 


1 
1 

9 * 


7 
2 
254 


Sequential 
Text Files: 


Byte B 
Relative Field R 
Absolute Field (EXEC) R 


s 




32767 
32767 
32767 


Random-Access 
Text Files: 


Record Length 
Record Number 


L 
R 


1 




32767 
32767 


Binary Files: 


Starting Address 
Number of Bytes 


A 

L 


9 

1 


65535 
32767 




DOS Command 


Quantity 

■ 


Range 
Minimum 


Maximum 




PR* s 
INI s 


9 
9 


16 ** 
16 ** 
16 




HAXFILES n 


n 


1 


* Minimum 


volume number INIT will actually assign to a diskette Is 



« Maximum slot number built into the Apple II is 7. In deferred- 
execution mode only, the SYNTAX ERROR message is Riven for s values 
from 8 through 16* 

Note: The use of values outside the above ranges does not always cause the 
RANGE ERROR message- Any DOS command parameter or command quantity that 
is less than or greater than 65535 will cause the SYNTAX ERROR message, 
not the RANGE ERROR message. 



WRITE PROTECTED (ONERR GOTO code » 4) 

Occurs when DOS attempts to store information on a diskette, but the disk 

drive does not detect a "write-protect" notch or cutout on the left side 

of the diskette's outer case. The following are the most likely causes: 

I. There is an adhesive label placed over the diskette's write-protect 
cutout, to prevent accidentally over-writing or deleting any information 
on the diskette. This label may be removed, whereupon DOS will SAVE or 

BSAVE or WRITE to the diskette* 

2* There is no write-protect cutout on the diskette- This is true on the 
System Raster diskette, for maximum protection. While not recommended, it 
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Lh post*) hit- to carefull y cut a notch of exactly the correct size and in 
Deadly the correct place* Use another diskette's write-protect notch for 
n model . 

). If you receive this message while RUNning the COPY program, and the 
rniiHr Is not cither I or 2, above, you may have inserted the diskette into 
the drive Incorrectly (in any other situation, DOS gives the 1/0 ERROR 

message to signal incorrect diskette insertion). Check the diskette's 
position in the drive, and re-read Chapter l'a discussion on inserting 
diskettes. 



END OF DATA (ONKRR GOTO code - 5) 

Occurs when you try to retrieve information from a portion of a text file 
where no information has ever been stored. Any byte beyond the last field 
In n sequential text file, or beyond the last field of each record in a 
random-access text file, may contain the value 0. Zero is the ASCII code 
for a null character, a "nothing", and any command that causes the 
retrieval of this character results in the END OF DATA message- Remember 
that only OPEN automatically sets the position-in-the-f ile pointer back to 
the 'file's beginning. The message usually occurs after an INPUT or a GET 
command, and can arise in several different ways: 

1. Too many successive INPUTs or INPUT with too many variables. Each 
INPUT or INPUT variable causes one additional, adjacent field to be read 
into the Apple. 

2. Too many successive GETs. Each GET reads one additional, adjacent byte 
or character into the Apple* 

3. The B (for Byte) parameter was too large. In sequential files, this 
parameter must not specify a byte beyond the last RETURN character in the 

file. In random-access files, the B parameter should not specify a byte 
beyond the last RETURN character in the currently selected record. 
Remember, the first byte in a file or a record is byte 2* 

4. The R (for Relative-field position) parameter in a POSITION command was 
too large* In sequential files, this parameter must not specify a field 
beyond the last existing field in the file. In random-access files, 
POSITION'S R parameter should not specify a field beyond the last existing 
field in the currently selected record. 

Remember, the R parameter used with POSITION is not the same as the R 
parameter used with READ* It specifies a field position in the file, 
relative to the current file position and forward in the file, only. 
R0 specifies no change in the current file position* Rl jumps the file 
position ahead to the first byte following the field that contains the 
current position. 

POSITION scans forward through the contents of the file, byte by byte, 
looking for the Rp-th RETURN character. If it encounters a 1* byte (the 
mill character) before finding the required RETURN character, the END OF 
DATA message is given Immediately : it is not necessary actually to INPUT 
or GET the null character. 
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5* The It (for absolute-f leld position) parameter in an EXEC command was too 
large- This parameter may specify the first field beyond the last 
existing field in a file, but attempting to specify the second field 
beyond the file** end will cause the END OF DATA message. Remember, R0 
specifies the first field in a file* 

6* The R (for Record) parameter in a READ command specified a random-access 
file record in which nothing has yet been stored* Before you can READ 
from a particular record in a random-access file, you must first WRITE 

some information into that record* 

Remember, READ'S R parameter is not the same as the R parameter used by 
POSITION or EXEC. READ 'a R parameter specifies an absolute record in a 
file: Rfl is the file's first record, and so on, 

DOS usea the OPEN command's L parameter for calculating where the Rr-th 
record begins, so the OPEN preceding READ must use the same L parameter 
value as the OPEN that preceded WRITE for that file. 



FILE NOT FOUND (ON ERR GOTO code - 6) 

Occurs when certain DOS commands specify a file name that is not in the 
CATALOG for the diskette In the selected or default disk drive. Only the 
commands SAVE. BSAVE, INIT and OPEN can create a file whose name did not 
previously exist. In addition to these, CLOSE may be used with any valid 
name. A file name specified by any other DOS command must already exist on 
the diakette. 

This message may ariae in various ways: 1. You may have misspelled the 
file's name, by a typing error or by omitting the cornea that separates the 
file name from a following parameter. Check the CATALOG for the exact 
spelling of the file's name. Warning: if you have accidentally typed 
control characters into the name of a file, CATALOG will not display these 
characters. For help, see "File Names" in Appendix F* 

2. The file is on another diskette. Check the CATALOG. 

3. The file has been accidentally DELETEd. Check the CATALOG* 

4. When you use the INIT command on a diakette, you specify a file nam* 
which DOS thereafter attempts to RUN each time you boot the system with that 
diskette in disk drive 1. Unless you write a BASIC program, and save It 
using the name plven to INIT, the FILE NOT FOUND message will be given each 
time the system is booted with that diskette in drive 1* If you can t 
remember the name of this "greeting program", you must re-INIT the disk, 

or run MASTER CREATE to rename the greeting program without destroying the 
contents of the diskette. 

VOLUME MISMATCH (ONERR GOTO code - 7) 

Occurs when the Volume (V) parameter used in a DOS command is not the same 
as the volume number assigned to the diskette in the default or selected 
disk drive, when that diskette was INITlalized. The volume number of a 
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diakette is shown at the head of each CATALOG display. Unless a DOS 

(Mimfhsnil Hpeeifiea A particular volume, the diskette's volume number la 
Ignored, and no message is given. If a DOS command specifies volume 0, the 

diskette's volume number la still ignored. If no volume number is given 
with INIT, or If volume number la given, the diskette will be initialized 
with the default volume number 254. 

I/O ERROR (ONERR GOTO code - 6) 

Occurs after en unsuccessful attempt to store data on a diskette or to 
retrieve data from a diakette (DOS tries 96 times, then gives up). This 
message can occur in the following ways: 

1. The selected or default drive'e door is open. Close the door to the 
disk drive. 

2* No diskette in the selected or default disk drive. Put a diakette into 
the drive and close the drive door. 

3* Diskette in the selected or default disk drive has not been 
INITialUed. INIT the diskette. 

ft. Diskette is inserted incorrectly. Check the diskette, and re-read the 
section in Chapter 1 on Inserting diskettes. 

5. During execution of a VERIFY command, DOS found the specified file waa 
not stored correctly on the diskette* If the file's information la still 
in memory, try storing it again (perhaps on a different diskette). 

6. The DOS command's D (Drive) parameter has specified a disk drive that 
does not exist in this system. The default drive la now the non-existent 
drive. Just specify the correct D parameter with the next DOS command to 
reset the default* 

7. The system is trying to access a 1 >-sector diskette using 16-sector DOS. 
Use the MUFFIN program to update your diskette to 16-sectors* 

8. The DOS comnand'a S (Slot) parameter has specified a slot that does not 
contain a dlak controller card in this system. 

e 

You are in trouble, but can still save yourself; don't despair. The 
problem is that the default slot is now the empty slot your last DOS 
command specified* The next DOS command without a slot parameter will go 

to the empty slot and return the same message as before. To reset the slot 
correctly, 

a) Press RESET 

b) If you see a Monitor prompt (*), type 3D0C 

c) Type CATALOG Ss where s is the correct slot* 
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DISK PULL (ONER It GOTO code » 9) 



Occurs when DOS attempts to score information on n diskette*, and finds that 
no more storage space is available on that diskette. A maximum of 496 
sectors can been filled with user-stored Information, as displayed in the 
CATALOG (if an Individual file exceeds 255 sectors, the CATALOG display of 
Its length starts over again at 00f>>. If you receive the DISK FULL 
message, rest assured that all files are CLOSEd, and that DOS saved for 
you all tt could (leaving you with some portion of your file not on the 
diskette). If you receive this nessoge while saving a file called STUFF, 
the first thing you should do Is to 
DELETE STUFF 

and then save your program on another diskette that has nore room left. 



lf you receive the DISK FULL message and then Immediately try to SAVE, 
8 SAVE or WRITE any file on the diskette before DELETClng any files, then 
(are you ready?) the sector length of the one of the entries shown in the 

CATALOG will be set to 0. Don't despair: despite the odd appearance of 
that entry's CATALOG display, the file itself la in fine shape* To avoid 
such situations* if you get a DISK TOLL message, DELETE some files before 
trying to save other files. 



FILE LOCKED (ONERR GOTO code - !0) 

Occurs when you try to 5AVE, BSAVE, WRITE or DELETE using a file nane that 

has been LOCKed on the diskette that is in the selected or default drive. 
Check the CATALOG display: the names of LOCKed files are preceded by an 
asterisk ( * ) In the CATALOG display. A file la LOCKed to prevent 
accidental over- writing- Use another diskette or UNLOCK the desired file. 



SYNTAX EEROR (ON ERR GOTO code - U) 

Occurs when DOS encounters a syntax error in a DOS command. Check the 

manual for the exact syntax required for the command in question* The 
problem may be a ncn-valid file name (see Appendix F) B an incorrect 

parameter symbol, a missing parameter, a missing or Incorrect separator 
(usually a comma). This message will also arise if a parameter value or 
command quantity la a negative number or is greater than 65535. 

Rarely, every DOS command causes the Applesoft or Integer BASIC Syntax 
Error message. This usually means that DOS has not been booted or has 
become "disconnected" from input and output* Try pressing the RESET key 
then typing 3D0C to reconnect DOS; or, re-boot the disk* 
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HO BUFFERS AVAILABLE (ONERR GOTO code - 12) 



ncriirn when a DOS command requires* another file buffer for input or 
output, and all the available file buffers are already in use* On booting 
the system, DOS reserves enough space in the Apple's memory for three 
I nput *nnd~output file buffers* A subsequent MAXFILES command can increase 
or decrease the number of available file buffers, and a CLOSE command can 
release file buffers currently in use for text files. 

Many (KiS commands use one file buffer for input or output during their 
execution, and then relinquish that buffer when execution of the command 
has ceased* 

When a text file Is OPENed, a file buffer is assigned to that file for 
input and output- This buffer remains in use, generally, until its file 
ie* CLOSEd either specifically by file name or by the nameless CLOSE that 
de-allocates all the text-file buffers. A text flic 1* not automatically 
CLOSEd by a program's coming to an end. To conserve buffer space, CLOSE 
files as soon as you are through using them. Remember that the next OPEN 
will re-sot the positioo-io-the-f i le pointer to the file's beginning. 

The MAXFILES command can be used to increase buffer space befo re writing 
the program or loading the program into memory* Increasing MAXFILES moves 
HI HEM down, and this can erase stored Integer BASIC program lines or 
Applesoft strings* Changing MAXFILES in the middle of a program can be 
especial ly dangerous ■ 



FILE TYPE MISMATCH (ONERR GOTO code « 13) 

Occurs when a DOS command attempts to use a file name that is already 
assigned to a file whose file type is Inappropriate to the present 

command. If you are sure the command Is correct, use a file name that Is 
not now on the diskette, use a different diskette, RENAME the existing 

file or DELETE the existing file. 

This message arises from several different Incorrect combinations of D05 
commands with existing file types* Here are the correct combinations: 

LOAD f, RUN f, SAVE f f must be an Applesoft or Integer 

BASIC program file. 

CHAIN f f must be an Integer BASIC program file. 

OPEN f. READ f, WRITE f, f must be a text file. 

APPEND f, POSITION f, EXEC f 

BLOAD f, BRUN f, BSAVE f f must be a binary program or data file. 

The greeting program's file name, specified with INIT or UPDATE, 
must refer to an Applesoft or Integer BASIC program file. 
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PftOGftAH TOO LARGE (ONERR GOTO code - 14) 



Occurs when a DOS command Attempt* to place a diskette file Into Apple** 

memory, and finds the available raeaory Insufficient to contain the entire 

flic. You (or a previous program) may have set HIMEM too low for the 

current task, or a Urge MAXF1LES may have set BIMEW too low. If you set 

the number of file buffers to three, using the command 
HAXPILES 3 

then HIMEM will be returned to the booted value given In Appendix D, Table 
2« 

OP 

If you are In Integer BASIC, and H1HEM ia set low (to protect the 
high-resolution screen raeoory, for instance), you nay experience trouble 
on shifting to diskette Applesoft- Diskette Applesoft occupies about 

1Z.5K of memory, but a shift to diskette Applesoft (with FP or LOAD or 
RUN) does not reset HIMEM to maximum* Uhen DOS tries to load the 
Applesoft program from diskette, the message PROGRAK TOO LARGE will be 
given if HIMEM is below about 13180. The system will be left in Integer 

BASIC again, and you nust set HIMEM higher from Integer BASIC. See 
Appendix D, Table 2 for your system's maximum HIMEM with DOS and three 
file buffers* 

® 

In deciding whether or not a program will fit Into the available memory, 

DOS looks only at the number of diskette sectors occupied by the 

program- In general, the program does not completely fill the last sector 

(256 bytes), but DOS ignores this fact* DOS compares only the high-order 
byte of LOMEM (Integer BASIC) or HIMEM (Applesoft) with the high-order 
byte of the projected end»of -program location* Thus a program which 
should fit into memory, but which would leave less than 256 bytes of free 
memory after loading, may cause the PROGRAM TOO LARGE message. Sometimes 

this can be corrected by ooving HIMEM or LOMEM slightly, to change the 
high-order byte, before loading the program. 



NOT DIRECT COMMAND (ON ERR GOTO code - 15) 

Occurs when you try to use one of the text file commands APPEND, OPEN, 
POSITION, READ or WRITE from Immediate-execution mode* These DOS commands 
can be used only from within PRINT statements in program lines- 
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This appendix tells how information is stored on a diskette, and how DOS 
remembers where particular information has been stored. 



In the following diacuasion, a dollar sign ( S ) or the label "Hen" 
preceding a number indicates that the number la expressed in hexadecimal. 

OVERVIEW OF THE STORAGE PROCESS 

In the Disk 11 system* information is recorded on a diskette In 35 
concentric zones or bands, called tracka. These tracks are numbered from 

track $M» the outermost* through track $22, the innermost- The disk 
drive's recording and reading head can be moved In and out f to stop and 
hover over each of these 35 different zones of the spinning diskette* 

Furthermore* the length of each track on the diskette Is divided into 16 
segments, called sectors. These sectors are numbered from $0 through SF, 
and up to 256 ($1 00) bytes of information can be stored In each sector. 
Once the disk drive's recording and reading head is positioned over a given 
track* that track's 16 sectors will pass under the head, one after the 
other* each time the diskette spins around. D05 always records information 
on the diskette in 256-byte chunks, exactly filling one sector each time. 

To store information on the diskette* DOS first puts 256 bytes (one 
sector's worth) of the information in an area of Apple's memory called I 
file buffer. When this file buffer is full* the information la stored in 
one sector on the diskette. Then DOS fills Apple's file buffer with the 
next 256 bytes of information and stores that information on the diskette. 

In general* DOS will begin storing a program or text file wherever it can 

find an unused sector on the diskette. When that sector Is filled with 
its 256 bytes of information* DOS finds another free sector* perhaps on 

another track* and continues to record information there. This process 
continues until the entire file has been stored. 

To remember which sectors of which tracks contain the information for a 
particular file* DOS makes up a list of each track and sector used, as it 

stores the file. Then DOS stores that list, called a track/sector list, in 
yet another free sector <or sectors) on the diskette* 

Finally, the file's name, file*-type* length in sectors* and the diskette 
location of the file's track/sector list are recorded in a special area of 
track 911 called the directory. At this time* too* the diskette's track 
bit map Is updated to correctly show which sectors of each track are 
currently in use. 

WRITING INTO A SEQUENTIAL TEXT FILE 

Entries in a text file consist of 1 to 32767 characters stored .is their 
equivalent ASCII codes and ended by a RETURN character (either ASCII $0D or 
ASCII $8D). Each such entry Is called a field. 
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In a sequential text file (no Length parameter specified when the file was 
OPRNed). fields are stored immediately following each other (sec Chapter 
6). DOS writes the first byte of each new field immediately following the 
RETURN character that ended the previous field (unless otherwise 
instructed by a Byte parameter)- Each time the file is OPENed, DOS 
forgets the current position within the file* and starts WRITElng again In 
byte 9 (again, unless otherwise instructed by a Byte parameter) - 

In order to re-write a particular field or character within a sequential 
file, WRITE can be used with the B (for Byte) parameter to begin writing 
at the specified, absolute byte of the file (the first byte in the file 
is byte 0, the next is byte I, etc.). The byte specified may be before or 
after the current position in the file. 

It 1b very difficult to remember exactly which character appears In every 
byte of a tent file, especially in a sequential text file. For this 
reason, use of the Byte parameter In sequential text files Is not 
recommended . 



The POSITION command can be used with an B (for Relative-field) 
parameter to move a pointer ahead (only) through the file a specified 
number of fields relative to the current position in the file. A 
program portion such as 

12* PRINT li' -OPEN NANES~ 

138 PRINT Mi -POSITION MfflES. Rl 

3" 

14* PRINT 09- "WRITE NRHES" 
tei» PRINT -APPLE COMPUTE*" 

tr* print v+> "Close NflPES" 

will attempt to WRITE the characters APPLE COMPUTER into the NAMES file, 
beginning in the first byte of the fourteenth field (the first field is 
Relative-field 0). 

POSITION can move you to the first byte of any given field Relative to the 
current position in a sequential text file. If you then re-WRITE that 
field, however, vou must make sure thnt you re-PR INT exactly the same 
number of characters that you PRINTed In that field originally. If you 
PRINT fewer characters, you will have created two new fields! the field 
you just PRINTed, and the tail-end of the original field you were 
over-writing. If you PRINT more characters than the original field 
contained, you will have over-written boihc of the characters at the start 
ol the next field. 
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WRfflNG INTO A RANDOM-ACCESS TEXT FILE 



For a random-access text file, a Length parameter Is specified when the 
file is OPENed. The Length parameter determines the number of bytes in a 
record, which is a field or a collection of fields that DOS treats as a 
unit. Each record in a random-access text file is like a separate 
sequential text file whose maximum total length has been specified by the 
Length parameter- As long as you stay within that maximum Length, you can 
WRITE and re-WRITE all you want, without affecting any other record in the 
file. WRITE can be uaed with the R <for Record) and B (for Byte) 
parameters to begin writing into any byte of a specified record. 

$ 

Since an^ DOS command will terminate WRlTE-ing, you cannot use POSITION 
to Jump ahead into different fields within the record specified by the 
WRITE command. 



DOS uses the Length parameter to calculate where to write the first byte 
of each new record ( L bytes beyond the first byte of the previous 
record). DOS simply skips over any bytes between the previous record's 
last character and byte U The bytes skipped over will continue to 
contain whatever values were stored there at some earlier time (see the 
next section for details). 

If you attempt to WRITE more characters in a random-access record than 

you specified in the Length parameter, all the characters are stored 

correctly on the diskette. However, when you begin WRITEing to the next 

record, DOS calculates the new record's starting position as if the 

previous record had been within the specified Length. The new record thus 

overwrites the last characters of the previous, over-sised record. 

Including the end-marking RETURN character of the previous record's last 
field. The result Is messy. 



HOW DOS WRITES WTO TEXT FILES: GENERAL PROCEDURE 

When you WRITE a field into a text file, DOS first checks on the diskette 
to see whether or not you have already stored information in the sector 
which should contain that field. If your file has never used that sector 
before, DOS places zeros in all 256 bytes of an Apple file buffer, and 
then lets you put your information into chat buffer for later storage In 
the correct diskette sector. The contents of the file buffer are stored 
on the diskette when your information haa completely filled 256 bytes of 
the buffer, or when the file is CLOSEd. 

Thus, when you WRITE to a particular sector the first time , unused 
bytes are given the value zero. An attempt to READ a byte containing a 
xero (the ASCII code for the null character) will result in the messaee 
END OF DATA 
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Bui if DOS finds your file has already stored information in the sector 
which should contain the field that you are now WRITEing, it reads all 256 
byte* from that sector into the Apple's file buffer. After you have 
changed any of those file-buffer bytes to contain your new information — 
the WRITE, POSITION (sequential files only) and PRINT commands take care 
of this for you — DOS then stores the buffer's contents right back into 
the the name diskette sector where they originated. The contents of the 
file buffer are stored back on the diskette when you attempt to change any 
byte not in the sector that was read into the file buffer, or when the 
file Is CLOSEd. 

Thus, if you BUTE more information for a file, and DOS stores that 
information in a diskette sector already being used by your file, this 
will not re-write any zeros in unused bytes. Any of those sector bytes 
which you did not re-wrlte will continue to contain whatever information 
might have been stored there before your WRITE command. This is true of 
the unused bytes at the end of a sequential text file, and also true of 
the unused bytes in each fixed-length record of a random-access text file- 



CON1BITS OF FILE SECTORS 

Now that you know the general process of recording a file on diskette, we 
can discuss each element in more detail. The actual information stored, 
sector by sector, is different for each type of file. 



FORMAT OF FILE SECTORS 
for different file types 



Pile 

BASIC 
(both 
types) 



1st sector 



Subsequent 
sectors 



Byte 
(Hex) 



2 through FF 

All 
bytes 



Contents of byte 



Program length, low byte 
" , high byte 



Token ized program 
Tokenised program 



Teist All All ASCII representation of 

sectors bytes text! one byte/character 

($M marks end of file) 
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File 



Binary 



Sector 
1st sector 



Subsequent 
sectors 



Byte 
(Hex! 

1 

2 
3 

4 through FP 

All 
bytes 



Contents of byte 



Starting RAM address* low byte 
" t high byte 

Length of RAM image, low byte 
' - high byte 



Binary data 
Binary data 



THE TRACK/SECTOR UST 

As a file is stored on the diskette, DOS makes a list of the diskette 
locations used by the file- This track/sector list is then stored on th< 
diskette in the same way the file itself was stored. The contents of a 
track/sector list are as follows: 



Byte 
( Hex) 

fl 

1 

2 



3 through 4 
7 through 8 

C 
D 



First Sector of a 
TRACK /SECTOR LIST 

Contents of b^te 

Not used 

Link: track number where continuation of the 

track/sector list My be found- 
Link: sector number where continuation of the 

track/sector list may be found. 

(If both bytes of Link - 0, no link.) 

Not used 

Sector base number (counts groups of 122 sectors) 
Not used 

Track number of first file sector 
Sector 



Track nuiriber of second file sector 
Sector 



10 
11 



Track number of third file sector 
Sector 



FF 



Track number of 122nd file sector 
Sector 



128 



If any track/sector pair 1b 0/0 this indicates an unassigned sector 
(initially the end of the file, although text files may contain 0/0 
Indicators for many as-yet-unassigned sectors where future bytes or 
record* «ay be written). 

Subsequent sectors of the track/sector list (if the list extends beyond 
122 track/sector pairs) are Identical to the first sector described above, 
except that the track/sector pairs refer to subsequent groups of 122 file 
sectors. Also, Link bytes 1 and 2 will be different for each subsequent 
sector. Each Link pair gives DOS the diskette location of the next 
portion of the track/sector list. If both bytes of the Link arc 0, this 
Indicates the final portion of the track/sector list. 

With a text file, only the track/sector pairs for those sectors actually 

containing information appear as non-zero in the track/sector list. DOS 
calculates the correct position for the track/sector pair within the list, 
filling unassigned track/sector pairs with zeros. 

Thus, if the Length parameter for a randoa-access file is 128 (two records 
pvr sector) and you WRITE only to record number 2700, thirteen diskette 
sectors are used: one for the contents of record number 2700, and twelve 
for the sectors of the track/sector list- The contents of records number 
through 2683 may someday occupy 1342 sectors; but until those records are 
written, they do not use any diskette space. The track/sector list giving 

the locations of the sectors containing records number to 2683 occupy 
eleven sectors. 



THE DISKETTE DIRECTORY 

On every INITiatired diskette, track $11 Is reserved for information 
concerning the content, of the diskette. This is where DOS stores the 
directory containing, for each file, the file's name. Its file type, the 
number of sectors occupied by the file (MOD 256), and the diskette 
location of the file's track/sector list. The CATALOG command causes 
most of this information to be displayed on the screen. Each sector of a 
diskette directory is formatted as follows: 



One sector of a DISKETTE DIRECTORY 
Byte (Hex) Contents of byte 

Not used 

1 Link: Track number where continuation of the 

directory may be found (normally $11) 

2 Link: Sector number where continuation of the 

directory may be found 

(If both bytes of Link - 0, no link.) 
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Byte (Hex) 
3 through A 
B through 2D 
2E through 50 
51 through 73 

74 through 96 
97 through B9 
BA through DC 

DD through FF 



Contents of byte 



Directory entry for file 1 

Directory entry for file 2 

Directory entry for file 3 

Directory entry for file 4 

Directory entry for file 5 

Directory entry for file 6 

Directory entry for file 7 



(see below) 



:: 



The file numbers shown for the seven directory entries sre arbitrary- When 
a file is DELETEd, DOS marks the directory entry for that file (see 
following table). The next time a file Is stored, DOS replaces the old 
marked directory entry with the directory entry for the new file. Thus* 
while DOS originally fills the directory in the order shown, file 
DQ,ETEions soon render this order meaningless. 

The diskette directory begins in track $11, sector $F. If more space is 
needed to store additional directory entries, sector $F is Linked to sector 
$E. If still mare space Is needed, sector $E is Linked to sector $D, and 
so on, through sector SI. This allows the directory to store directory 
entries for a maximum of 105 different files. 

Each directory entry is written in the following format: 

DIRECTORY ENTRY FOR ONE FILE 



I 
2 

3 through 29 
21-22 



Contents of Byte 



Track number of the file's track/sector list 

(The original value is copied into 20 and the value 
of byte Is changed to $FF when the file is 
DELETEd- ) 

Sector nunber of the file's track/sector list 
File type (see discussion on the next page) 
File 



Sector count: the number of diskette sectors 
(MOD 256) occupied by the file 
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A directory entry's relative bvtc specifies each byte within the entry, 
although each entry starts at a different actual byte number within the 
directory sector. To find the absolute sector byte corresponding to a 
relative byte, add the relative byte to the entry's first absolute sector 
hyle (ns listed In the previous table). 

Because only one byte is used to store a file's sector count, the maximum 
directory sector count Is 255 ($FF>. If a file exceeds 255 sectors, its 
sector count (as displayed by CATALOG) starts over again at 000. This 
does not affect use of the file, but may give an erroneous iopression of 
how full the diskette is. 

The eight bits of a file's type-designating byte, relative byte number 2 
in a file's directory entry (see previous table), are assigned values as 
follows: 

BYTE INDICATING THE FILE TYPE 

CATALOG 

Bit svPbol File type designated 



7 * File is locked (write protected) if this bit - 1 

File is unlocked (not protected) if this bit - 9 

b Expansion type for future use (normally zero) 
^ i» rt ii <• ii « •> 

^ H n ii n ff n ii 

j nwwtiftiiw 

2 B Binary file if this bit - 1 

1 A Applesoft BASIC file If this bit - 1 

I Integer BASIC file if this bit - 1 

T Text file if bits through 6 are all zero 



The file type is determined by a 1-bit appearing in one of the bits 
through 6. If bits through 6 are all 0-bits, the file type defaults to 
a Text file. 

The file's type-designating byte can thus take on the following values: 
VALUES FOR BYTE INDICATING FILE TYPE 



File Value of Type byte (He*) 

tipe File unlocked File locked 

Text # 8* 

Integer 1 81 

Applesoft 2 82 

Binary 4 86 
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VOLUME TABLE OF CONTENTS 



Sector $0 of crack $11 contains the diskette's Volume Table of Contents* or 
VTOC, The VTOC stores the following information: 



VOLUME TABLE OF CONTENTS (VTOC) 
Track $11 t Sector $0 
Value 

Description 



9 


2 


I 


11 


2 


0F 


3 


4 


4 





5 





6 


I through 



7 through 26 
27 

28 through 2F 

30 

31 

32 

33 

34 

35 

36 
37 





7A 



FF 
FF 
00 

00 

23 

0F 

00 
01 



Not used 

Track number of first directory sector 
Sector " " " " " 

DOS release number 

Not used 
■■ it 

Diskette volume number (default: $FE) 
Not used 

Maximum number of track/sector pairs possible 
in each sector of a track/sector list 

Not used 

These four bytes are a mask for the 

track bit maps (see next 2 pages): 
each 1-bit enables one of the 16 

sectors to be used in every track. 
Number of tracks per diskette 
Number of sectors per track 



Number of bytes per sector, low byte 

high byte 



T 



38 through 3B 
3C through 3F 

4fl through 43 



9 

3 



Track bit map 
Track I bit map 

Track 2 bi t nap 



(These tracks 
not available 

to the user) 



44 and 45 
46 and 47 



Track 3 M t map 
it #t n 



( Continued on next page J 
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Byte 

48 and 49 
4A and 4B 



78 and 79 
7A and 7B 



Value 
( Hex) 



Description 



Track 4 bit map 
ii ■■ ■■ ii 



Track S10 bit map 
ii ii ii n 



7C through 7F 



Track SI 1 bit map (Directory & VTOC) 



80 and 81 
82 and 83 



C0 and CI 
C2 and C3 



Track SI 2 bit map 



Track 



$22 bit map 



C4 through FF 



Not used 



TRACK BIT MAP 

Starting in byte S38 of the VTOC (see previous table), subsequent four-byte 
groups each contain the track bit map for one of the diskette's 35 tracks. 
The arrangement of 1-bits and fi-bl ts within a track's bit map shows DOS 
which sectors of that diskette track are currently in use, and which 



sectors are free. The bit map for each track 

TRACK BIT MAP 
For one diskette track 



Byte 
1st 



Designated 
Sector 
lit (Hex) 



F 

E 
D 
C 
B 
A 
9 




the following format: 



Bit 

7 

6 
5 
4 

3 
2 

1 





Designated 
Sector 
( Hex) 

7 

6 
5 

4 
3 
2 

1 




3rd t 4th All 



Spare 
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If a bit In the track bit nap contains the value I, the sector 
corresponding to that bit is free. If a bit in the map contains the value 
0* the sector corresponding to that bit is currently in use* Bits rarked 
"Spare" in the table above contain the value 0; these bits are not used. 
The track bit map for a typical track might appear as follows: 



1st byte 

I I 

\ f HUH 

FEDCBA98 



TYPICAL TRACK BIT MAP 

2nd byte 3rd byte 



1 1 I 1 I 1 1 I 

t t t t M ! t 

7 6 5 4 3 2 10 



Sectors designated 



00000000 



Spare 



4th byte 

Spare 



Hot used 



1 * Free sector (assuming the corresponding bit of the mask, 

VTOC bytes $30 through $33, is also I) 

- Sector In use 



When a file is being stored on the diskette (using WRITS, SAVE or BSAVD , 
an entire track is allocated to the file at once (when possible), and the 
track's bit map shows the entire track In use* Then* when the file is 
CLOSEd, those sectors not actually used are again designated as free* in 
the bit map for that track. 



Sectors actually used to store a file's information, however* can only be 
"set free" when that file name if* DELFTEd. Suppose your diskette contains 
a 100-sector BASIC file named BIG* for instance. If you now SAVE* on the 

sane diskette* a 2-sector file with the same nave Bin (overwriting the old 
file) a CATALOG of the diskette will reveal that your 2-sector file BIG Is 
still using up 100 sectors. To free up unnecessary sectors used by a 
BASIC file named BIG* use the following sequence of commands: 
LOAD BIG 
DFLETE BIG 
SAVE BIG 

A similar process 
binary files* 



can be used to release unneccessary sectors used by 



To release unneccessary sectors being used by a text file, you will have to 
READ each of the file's fields into the Apple* If you store all the 

array, you can then DELETE the original file before URITEing 



fields in an 
each record bai 
way to do this 
the field back 



k onto the diskette using the original file name. Another 
is to read each field into the Apple and immediately WRITE 
onto the diskette using a file name that is different from 



the original file name. When you have read and re-written the last field* 
you can DELETE the original file* 
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TRACK AND SECTOR ALLOCATION ORDER 

Each diskette contains 35 tracks* three of which are reserved for DOS and 
one for the Directory* leaving 31 tracks for the user- Each track 
contains 16 sectors* so all together 31*16 or £96 sectors are available to 
the user* 

Sectors are filled starting with sector $F and working back to sector $0* 
Tracks are first filled starting with track SI 2 (just inside the 

dl rectory /VTOC trade) and proceeding Inward to track $22 (the innermost 
track). When track $22 has been filled* tracke are then filled starting 
with track $10 (Just outside the di rectory/VTOC track) and working outward 
to track S3 (the outermost track available to the user)* 




Directory /VTOC) 



ivfcett* 
TRACK ALLOCATION ORDER 



j 

SECTOR ALLOCATION ORDER 



Diskette 
Cover 



First 
Filled 



Last 
Pilled 



First 
Filled 



Last 
Pilled 



First: 
Then: 



512 
$10 



> 



$22 
303 



SF > $0 
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RETR1EVMG INFORMATION FROM THE DISK 



To retrieve a file fro* diskette, DOS follows the process used to store 
the file* but in reverse* After a command such as 
LOAD FILE 
or 

8 LOAD FILE 

for Instance, DOS Roe* to the diskette's file directory in track III* and 
finds the directory entry containing the name PILE. This entry also 
contains the diskette location (by track and sector) of the desired file's, 
track/sector list* D05 then goes to this track/sector list, and reads the 
first track/sector pair* This pair specifies the diskette location of the 
first sector containing the program named FILE. When DOS has read that 
first sector of program into the Apple* it returns to the track/sector 
list tor the location of the program's second sector, and so on* 



READING FROM A SEQUENTIAL FILE 

When READing from a sequential text file, with a program portion such as 
50 PRINT DS; "READ TEXTFILE" 
60 INPUT AS 

for instance, the general process is like that described for LOAD In p. a 
program file* However* only the sector containing the text file's next 
field (all characters from the current position in the flic through the 
next RETURN character) is read into the Apple's file buffer in response to 
the INPUT command* Then the actual sector bytes that make up the desired 
field are assigned to the variable AS. This process la repeated If the 
field extends over more than one diskette sector. Each subsequent INPUT 
command will cause reading of the file to resume, from the Apple's file 
buffer if it already contains the proper field, or by reading another 
diskette sector into the Apple* This continues until the last field is 
read or some command CLOSEs the file* 

By using the READ command with the B (for Byte) parameter, you can cause 
the next INPUT to begin reading from the specified absolute byte in the 
file (the file's first byte la 0, the next is 1. etc*)* This byte nay be 
before or after the current position within the file* To use this 
parameter effectively, however, you must know the contents of every byte 
in your file* The POSITION command uses the R (for Relative-field) 
parameter to move DOS's current-position pointer the specified number of 
fields forward (only) through the file, relative to the current position 
In the file. Each time you OPEN a file, DOS forgets Its current position 
in the file and starts READing again from the beginning of the file 
(unless otherwise instructed by a Byte parameter)* 

The INPUT command treats a response somewhat differently In Integer BASIC 
and in Applesoft* If certain characters such as the colon or comma appear 
in the response field* further characters In the field may be ignored or 
assigned to multiple INPUT variables (if any). For details, see the 
appropriate manual for Integer BASIC or for Applesoft* 
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READING FROM A RANDOM-ACCESS FILE 

The text-reading process Is somewhat different when READing from a 
specified record of a random-access text file (also see WHITING TO A 
RANDOM-ACCESS FILE in this appendix). In a random-access text file, each 
record is composed of the same number of bytes, specified in the Length 
parameter when the file was OPENed prior to WRITElng the file. When this 
same file la OPENed prior to READing it, an identical Length parameter Is 
given. To find the beginning of a particular record (specified by the 
READ command's R parameter), DOS uses the Length parameter to calculate 
the number of bytes occupied by all the preceding records* That number is 
then divided by 256 ($100) to determine how many file sectors DOS must 
skip over to reach the sector containing the desired record. Then DOS 
examines the file's track/sector list and finds the diskette location of 
the desired file sector. Finally, DOS reads the correct sector into the 
Apple's file buffer. Then the correct bytes can be read from the file 
buffer- 

This same retrieval process would be followed even if the text file had 
originally been stared as a sequential file, or as a random-access file 
using a completely different Length. DOS blindly calculates the sector 
and byte position of the requested record according to whatever Length 
parameter you specify when you OPEN the file prior to READing from it, 
regardless of the Length parameter (if any) that was used when WRITEing 
the ftle in the first place* 

By using the READ command with both R (for Record) and B (for Byte) 
parameters, you can cause the next INPUT to begin reading from the 
specified absolute byte in the specified record (each record's first 
byte is 0, the next is 1, etc.)- This byte may be before or after the 
current position within the record- To use this parameter effectively, 
however, you must know the contents of every byte in the specified record. 

The POSITION command, while primarily intended for access to sequential 
flies, can be used with the R (for Relative-field) parameter to move 
DOS'a current-position pointer the specified number of fields forward 
(only) through the current record, relative to the current position in the 
record- READ is used with the R (for Record, this time) parameter to 
move the current-position pointer to the beginning of the desired record. 
Using POSITION cancels READ mode (without resetting the position-pointer) , 
and another READ (this time, with no parameter) re-instates READ mode. 

Each time you OPEN a file, DOS forgets its current position io the file 
and starts READing again from the beginning of the file (unless otherwise 
instructed by a Byte and/or Record parameter). 

x 

DOS keeps do information for you concerning the structure, format, 
record- length, or field-length of your text files* To use your 
random-access text files effectively, vou must keep detailed written 
information about the structure of these files, or keep the information at 
the beginning of the file.- 
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APPENDIX D 



140 Hiuasry Araaa Ov*t-Urlttaa When Booting DOS 
Ul tteBory Ax««a Used by DOS end Rithar BASIC 
142 HtMEX Set by Booting DOS 



TABLE 1; APPLE II MEMORY MAPS 

A. MEMORY AREAS OVER-WRITTEN WHEN BOOTING DOS 



Location on 
Any system: 

Highest RAM 
memory address. 



DOS moves 
HIMEH here- 
[ Note 2 J 

16383 (S3FFF). 



7424 C$1000)- 

6912 (S1B00)- 

2 303 (S8FFV 

2048 ($800)- 
1023 ($3FF>- 




512 <$200> 



Location on a 
48K system: 

-49151 (SBFFF) 



Relocated DOS, 
on completion 
of boot 



7 byte* not used 



Three file 
buffers of 
595 (9253) bytes 
for input & output 



DOS, where first booted 

fro* a Master diskette 
[ Note 1 ] 



DOS Relocation Code 
[ Note I I 



4192 (S9D00) 
10184 (S9CF8) 



^38400 (S9600) 



First stage boot 
starts here 



"Nibble" buffers 
used during boot 



Lowest RAM 
Memory add res 
000 (5000) 

Note I* This memory area Is not affected when booting a Slave diskette: 
DOS is placed directly below the Highest RAH Memory address that was 
available on the system that INITielUed the Slave diskette, whether 
appropriate to the preaent system or not. 
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B MEMORY AREAS USED BY DOS AND EITHER BASIC 



Highest RAH 
memory address'. 

49151 (SBPFF) 
on a 48K aystei 



24576 
($6900) 



16384 



8192 
C920MJ 



1752 
(S2A00) 
bytea 



Disk 

Operating 
System 
(If booted) 



Integet BASIC 
program lines 
start at HIMEH 
and :mi u down 



Applesoft 
strings 
stsrt at HIHEH 
and build down 

» 



High-resolution graphics, Psge 2 
I Note 5 J 



High-resolution graphics, Page I 

T 



Note 6 J 



I 



Either BASIC'S 
variables 

start at LOMEM 
and build up 

Applesoft 
program lines i 
push LOMEM up I 



1" 

\ 
I 
I 
I 
J 



Diskette 
Applesoft 
(if used) 
occupies 
this space 
1 Note 4 1 

1 

I 

I 

I 

! 



Without DOS, 

either BASIC 
sets HIMKM here 

1 Hots 2 1 



Hooting DOS 
late HIMEH here 
[ Note 2 ) 



FP (diskette) 
sets LOMEM at 
12291 (S3M3) 
i Note 2 ] 



(S0800) 




BASIC Systen use: 
low-resolution graphics 


Lowest RAM 




and text sere en v etc* 


tactsory address: * 
0000 ($0000) 


3D0 


3FF DOS + System 


340 — 


300 


- 3CF 


Monitor and BASIC Workspace 



FP (firmware) 
and INT set 

LCHEM here 
[ Note 2 ] 



Vectors 
Reserved 



Note 2- If your system is in Integer BASIC, the HIMEH pointer can be found 
(low byte first, then high byte) In locations 76-77 ($4C-$4D). If your 
system la in APPLESOFT BASIC, the HI HUM pointer ia in locations 
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115*116 <$73-$74), same format. See Table 2 for the value of HIHEM set by 
booting DOS- Increasing MAXFILES will move HIHEM down an additional 595 
bytes for each file buffer added- For the locations of other Applesoft 
program pointers, consult your Applesoft It BASIC Programming Manual. 
Appendix I. 



TABLE 2: HIMEM VALUE SET BY BOOTMO DOS 

When DOS la booted, HIHEM is set according to the amount of memory in the 
ays ten: 



System 


Highest 


RAM address 


HIMEM: set 


by DOS boot 


site 


Decimal 


Hexadec laal 


Decimal 


Hexadecimal 


16K 


16383 


S3FFF 


5632 


SI 600 


20K 


20b 79 


$4FPF 


9728 


S2600 


2AK 


26575 


S5FFF 


13824 


$3600 


32K 


32767 


S7PFF 


22016 


55600 


36K 


36863 


S8FFF 


26112 


S6600 


48K 


49151 


SBFFF 


-27136 


S9600 ( Note 3 



Note 3, The number -27136 could also be written 384M, but Integer BASIC 
will not accept numbers greater than 32767. In Integer BASIC, memory 
addresses greater than 32767 mist be expressed as their negative 
equivalents. The negative equivalent of any positive decimal address n is 
( n - 65536 >. 

Note 6. Using high-resolution graphics Page 1 erases the contents of 
meoory locations 8192 through 16383* Unless DOS sets HIMEM to a value 
greater than 16383, an attempt to use high-resolution graphics Page I will 
erase part of DOS. This meana that you cannot use Disk II and 
high-resolution graphics at the sane time, unless your system contains at 
least 32K of memory. 

If you are using diskette Applesoft, an attempt to use high-resolution 
graphics Page 1 will erase part of Applesoft. With dfskette Applesoft, 
you may use high-resolution graphics Page 2, only, if your system contains 
at least 36K of memory. See Note 5. 

Note 5. Using high-resolution graphics Page 2 erases the contents of 
memory locations 16384 through 24575. Unless DOS sets HIMEM to a value 
greater than 24575, an attempt to use high-resolution graphics Page 2 may 
erase part of DOS. This means that you cannot use Disk II and Page 2 
high-resolution graphics at the same time, unless your system contains at 
least 36K of memory. 
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DOS ENTRY POINTS 



Routine to re-conncct DOS (if page 3 Is over-written): 

System Decimal address Hexadecimal address 

48K -25153 S9DBF 

32K 23999 S5DBP 

16K 7615 S1DBF 

The Monitor command 3D9L displays this number at the top right. 



Locations containing the start address and length ol n BLOADed program: 

System Start address (low byte) Program length (low byte) 

>Ue Decimal Hexadecimal Decimal Hexadecimal 

4BK 43634 $AA?2 43616 $AA69 

J2K 27259 S6A72 27232 S6A&9 

16K 19866 S2A72 19848 S2A69 

To see the starting address or length after a BLOAD, type 
PRINT PEEK (low byte) + PEBKUov byte +1)*256 

Program to find the DOS locations containing the starting address 
and length of the most recently BLOADed program, on any size system: 

7 H - 3©40B REH COS-SOOT Hi*** 

8 T - 49152 ROl HIGHEST flOORESS 
19 D* - CMS* <4'j: REN CTRL-D 

2«* PRINT It, "0SfTVE fOO. W777T.. L#?7" 

38 PRINT t>«. "BLOW FPO" 

•8 PRINT frfc "DELETE F00" 

5© FOR I - H * 1791 TO T 

fcO IF PEEK <Z> <> 119 OR PEEK 

O + 1> < > US" THEN NEXT I 
TO PRINT "LOCUTIONS OF START 

HOORESS: *J|**- "(1*1 
9t> FOR I • M * 1792 TO T 
90 IF REEK <I> C > 119 OR PEE*. 

(I M) t > THEN NEXT I 
MS© PRINT -LGCftTlONS OF LENGTH: " 
j ti "j "l J * 1 

The values of H and T (lines 7 and 8) arc shown for a 48K system. 
Appendix D, page 142, shows the correct values for your system. 
This program takes about 2 minutes to find the desired locations. 



DOS character input and output routines: 

See Chapter 19, cxpeclolly Hote 7 on page 195. For an example 
using the technique described, see the program on page 151. 
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CIRCUIT SCHEMATIC: DISK II INTERFACE 
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CIRCUIT SCHEMATIC : DISK II ANALOG BOARD 
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DOS COMMANDS 




APPENDIX F 




te«yrati«l tejtt HI* Cttnftatrf* 
HacMns Up«««Bt file OmtMi* 




The D05 command* are grouped Into 5 categories in this appendix: 



H ousek e eping commands 
IN IT RENAME 
CATALOG DELETE 
SAVE LOCK 
WAD UNLOCK 
RUN 



VERIFY 
HON 
KOHON 
MAXFILES 



Access Commands 

FP PR# 
1ST IN* 



CHAIN 



Sequential Text File Cummnndb 



OPEN 
CLOSE 
READ 
WRITE 



APPEND 

POSITION 

EXEC 



R^ndom-Acceas Text Pile Commands 



OPEN 
CLOSE 



READ 
WRITE 



Machine LanRuaae Flic Commands 
BSAVE 

&LOAD 
I1RUK 



Procedures used in DOS (including chaining In Applesoft) are summarized in 
Appendix G. The notation used In the summaries (and throughout the 
manual) is described In the following section. 



NOTATION 

Syntax refers to the structure of a computer command- A simple notation 
is used to describe the syntax of each DOS command. 

Item* In square brackets, [ and 1 , arc optional. These items arc 
sometimes called parameters. Not all commands permit all parameters, but 

those parameters that are permitted in a given command may appear in any 
order, unless otherwise noted. 

If a command uses a file name, the file name must come Immediately after 
the command word itself: the first Item following the command will be 
treated as a file name. The file name must be separated by a comma from 
any parameter that follows. 

Curly brackets may be used to indicate when a certain key should be 
pressed: 

(CTRL) hold down the key marked "CTRL" while another key la typed. 
<CTRL)D means hold down the CTRL key while you type the 
letter D. Sometimes another notation is used: CTRL-D means 
the same as <CTRL>D. 
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(RETURN) press the key marked "RETURN" . The {RETURN) required 
after every command Is not shown* 

(RESET) press the key marked "RESET". 

<ESC) press the key marked "ESC". 



CAPITAL letters and commas must be typed as shown, lower case letters 
stand for Items that you must supply. 

f file name. This is from one to 30 characters. Any typoablc 

character except the comma may appear in a file name. The 
First character must be a letter of the alphabet. For more 
details, see the next section* 
Examples: CHESS 
RECIPE 

SUH OF SQUARES 
8HW45 

ROU-ABOUT-THIS 

g another file name. 

Example: SEPARATOR WITH LOW VELOCITY 

s slot number. s specifies the Apple II slot in which the 

disk controller card has been placed (usually slot 6). 
s initially defaults to the slot from which DOS was booted. 
It subsequently defaults to the last value specified for this 
parameter. s must be in the range 1 through 7. 
Examples: 7 




If s refers to a slot which does not contain a disk controller 
card, the system may stop and a program in memory may even 
be lost. See I/O ERROR, In Appendix B, for more details* 

v volume number of a diskette. v Initially defaults to the 

volume number of the diskette from which the system was booted. 
It subsequently defaults to the latest value specified for 
this parameter, or Implicitly specified by a CATALOG command, 
v must be In the range t through 254. 
Example: 101 

Note: A diskette's volume number may not be *. In a DOS 

command, specifying a volume number of or simply V 
with no number is a "wild card" and tells the DOS to 
determine and use the volume number on the diskette. 

d drive number (either 1 or 2). d initially defaults to one* 

It subsequently defaults to the latest value specified for 
this parameter* 
Example: 2 
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p position number. Used with the R parameter in the POSITION 

and EXEC commands Cor sequential text files. p specifies 
a field vhose position In the file is p fields ahead of the 
current file position. p defaults to 0, which does not move 
the file-position pointer in the file. Note: EXEC always sets 
the pointer to the start of the named file, so p is always 
relative to when used with EXEC. See command summaries later 
in this Appendix. p oust be in the range through 32767. 

r record number- Used with the R parameter in the READ and 

WRITE commands for random-access text files. r defaults 
to after OPEN. Thereafter, it defaults to the last record 
specified. r points to an absolute record within a randoo- 
sccess file. r must be in the range through 32767* 

a address in RAH. The a parameter is required with the BSAVE 

command. a specifies the starting Apple memory address for 
BSAVEing or BLOADing binary information. If BLOAP does not 
specify an a parameter, then the value of a defaults to 
that used when the binary file was BSAVEd* a must be in 
the range through 65535* 

b byte number. b defaults to 0. In a sequential file, b 

points to an absolute byte within the file. In a random-access 
file, b points to an absolute byte within the record pointed 
to by r - b must be in the range to 32767. For most 
applications b is in the range through the last byte tn 
the current sequential file or the last byte in the current 
random-access record * 

3 length specifier. j defaults to U When used In the OPEN 

command with random-access files, J Is required and specifies 
the number of bytes that will constitute a record in a random- 
access file- When used with the BSAVE command, J is required 
and specifies the number of bytes of Apple memory, starting at 
address a , whose contents are to be stored on diskette. j 
must be in the range through 32767. 



Am an example of this notation, the DOS command that Is notated 
INIT f [,Vv] [,Ss] [,Dd! 
can be interpreted as 
INIT HELLO, V17, D2 

by the following process. The keyword "ISIT" is In upper case, and must 
be typed exactly as shown- In the syntax description, "f" is lower case 
and stands for a file name — it is replaced by the legitimate file name 
"HELLO" in this example. The '\V17" is optional. "V" stands for 
"volume"; 17 was chosen arbitrarily as a volume number for this enample. 
The notation ",Ss" is optional and omitted. The notation ",Dd" becomes , 
D2 in this example, indicating that disk drive number 2 Is to be used. 

Any numerical constant in a DOS command can be entered in hexadecimal 
notation by preceedlng the hexadecimal digits with a dollar sign. 



1S0 



Rif NAMES 



fl)C names may be up to 30 characters long, and must begin with a letter. 
The name cannot contain a comma, a CTRL-H or a RETURN, which is used to 
terminate the command. Spaces that precode the first non-space character 
tn a name are Ignored. All name characters beyond the 30th are Ignored* 

m 

When typing file names, the use of special keys such as ESC, the 
left-arrow and right-arrow keys, and certain keys typed with the CTRL key 
("control" characters CTRL-C, CTRL-fl) may have unexpected effects* 

x 

If a file name contains control characters, you won't see them printed, 
but they must be typed to use or delete the file. 

The following Applesoft program can be used to find any hidden characters 
except CTRL-M (RETURN), ESC, CTRL-H (left arrow) and CTRL-U (right arrow). 

ll* DATA 1*1- £48' i'l- 1 > 

DIITfl 249* 17* 2©1 1*4^ 13 

Ml t«TR Kb Tfi. 245> 



SB CW.L iflK 

If you suspect you may have accidentally introduced a control character 
Into a file name, type this program, SAVE it, and RUN it. The Applesoft 
prompt ( 1 ) Will be displayed. Next type 
CATALOG 

ftttd you'll get a list of all the files, with any control characters shown 
as flashing characters. Control characters in program listings can also 
he found this way. To re-instate normal printouts, type 
I'M 9 



HOUSE KEEP i4G COMMANDS 



INIT f l,Vv| |,Ssl |,Dd) 
Kxomple: INIT HELLO, Vlfl 

The parameter v assigns a volume number to the diskette being initialized. 
Detail* on Initializing diskettes are In Chapter 2 and Appendix G» 
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CATALOG [,Ss] [*B*1 
Example: CATALOG 

Displays on the screen the volume number and a list of all flies on the 
diskette in the specified or default drive- The default volume number is 

changed to natch that of the indicated diskette* If this command uses a 
volume parameter I>VvJ that parameter la ignored* 

With each file la displayed an indicator of its flic type and the number of 
diskette sectors occupied by the file* The file types are: 

I Integer BASIC program file, created by SAVE* 

A Applesoft BASIC program flla. created by SAVE. 

T Text file, created by OPEN and filled by WRITE. 

B Binary memory-image file, created by B5AVE. 

An aaterlsk beside a file's type indicator shows that the file is LOCKed- 

A maximum of 496 diskette sectors are available to the user* Each diskette 
sector can store up to 256 bytes of information* The minimum length of a 

file is 1 sector* for an empty text file* (Technically, that 1 sector la 

occupied by the empty track/sector list for the file*) Empty Integer 

BASIC, Applesoft, and Machine Language files take 2 sectors* (I for the 

track/sector list and 1 for the first program sector, which contains the 

program's length. See Appendix C for more details-) 



If an Individual file exceeds 255 sectors, the CATALOG display of that 
file's length starts over at 000. This does not affect use of the file* 
but may give an erroneous impression of how full the diskette Is* 



SAVE f.t.SsJ f.Dd] I,WJ 
Example: SAVE COLOR DEMOS. V56 

If there is no file with the specified file name on the diskette in the 

specified or default drive, a flit is created on that dlakette and the 
current Integer BASIC or Applesoft program is stored under the given file 

name* If ths diskette contains a file with the specified file name* but 

of a different language or file type, then the message 

FILE TYPE MISMATCH 
will be displayed* 




If the chosen diskette already contains a file with the specified file 
name, and In the same language, the original file's contents are lost and 
the current BASIC program is savad in its place. No warning is given. 
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M»At> f |,SnI i,lkt| | . v • : 



Simpler LOAD HOW JONES, VI9, DI 

Atrrtnfitft to II mi Integer BASIC or Applesoft program file with name f on the 
ill -I i< i i 1 1 In the specified or default drive- If the volume numbers match and 
tli**re In audi a file, that program will be LOAflcd into the computer- It can 
i linn br LISTcd, or RUN, or SAVEd as with any program. LOAD closes any open 
text flics, changes the Apple to the correct language for file f , and 
erne** any program in memory before placing the new program in the Apple. 

If file f is an Applesoft BASIC program, and Applesoft la not already in 
memory or available from the Applesoft firmware ROM card, the program 
Applecnft will be LOADcd and RUN from the specified drive automatically, 
before file f is LOADcd* If Applesoft is not on that diskette nor on the 
firmware ROM card, the messape 
LANGUAGE MOT AVAILABLE 
will bo displayed* 

The instruction LOAD, without any parameters, will LOAD a program from 
ratmctt* tape* 



RUN f |,SsJ |,Dd) [,Vv] 
Example: RUN ANNUITY, D2 

LOADs file f from the specified or default drive (sec the previous 

dlscufision), then also RUNa the program loaded* If Just 

RUN 

la typed, the program in memory is RUN* 



RENAME f, g |,Ss] [,DdJ t,W) 

trample: RENAME SEPERATE, SEPARATE, S4, Dl , Vfl 

Kinds the file named f on the diskedte In the specified or default drive, 

and changes its name to r . The file's contents are not affected. If file 
f was open, it is closed* 

$ 

PKftAME does not check to see whether the file name g Is already in use, 
mo It lo possible to use RENAME to put several files of the some name onto 
a diskette — a potentially confusing situation, at best. 
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DELETE f USfi] [,Dd] I ,Vv] 



Example: DELETE TEST 

Renoves the file named f from the diskette In the specified or default 
drive* If f was open, this command closes it- See Appendix C for more 
details of the deletion process* 

3D 

If a file named f does not exist on the diskette, the message 
FILE NOT POUHD 

will result. To avoid this occurrence stopping your programs, first OPEN 
the file, then DELETE it* 

LOCK f l.SsJ (,Dd) [,Vv] 
Example: LOCK LOVE LETTERS, V31 

This command allows you to make file f , on the diskette In the specified 
or default drive, safe from accidental deletion or change. A LOCKed file 
is Indicated In the CATALOG by an asterisk ( * ). 



UNLOCK f f,Ss) MM] UVv] 
Example: UNLOCK RECIPES, V3I, D2 

If you change your mind, and want to alter or remove a LOCKed file named 
f p on the diskette in the specified or default drive, this command allows 
Such s change. 



VERIFY f [,Ss] l.Dd) UVv) 
Example: VERIFY SAM 

Performs a check that the information actually stored on the diskette in 
file f la self-consistent. (Technically, this la what happens: When 
the file is created — with SAVE, BSAVE or WRITE ~ DOS calculates a 
checksum byte for the contents of each output buffer and then stores that 
byte with the buffer's contents in a diskette sector. The VERIFY command 
calculates a new checksum byte for the actual contents of each file 
sector, and compares it with the checksum byte originally stored with that 
sector.) If a file VERlFYs, no message Is given; it's safe to assume the 
Information on the diskette has been stored correctly. If a file does not 
VERIFY, the message 
I/O ERROR 

Is presented. You may VERIFY any type of file. 
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HON |C] |, 1| 1,0) 



£xAmpl**»i: HON 

HON V. 9 1,0 

All disk commands and all information sent between the computer and the 
disk arc normally not displayed on the screen. This command allows you 
to pnable unnc or all of this display — a helpful tool when debugging a 
pronram. If C is specified then disk commands are displayed* If I 
in specified, then information being sent from the disk to the Apple, as 
Appl* - * will be displayed. If is specified, then Information 

being sent to the disk from the Apple, as Apple's output t will be 
displayed. 

At least one of the three parameters gggt be present, or MON Is ignored* 

The parameters may appear In any order, separated by commas. These 
parameters appear only In the commands MON and HOMON. 

Notet MON remains in effect until a NOHON command, a change of language 
(KP or INT), a boot, or a restart (3D0G). Even RUNning a program won't 
cancel a HON. 



NtiHON |C] UI| 1,0] 

Examples: NOMON C 

NO MON I, C 

The HON command enables you to display disk commands and/or Information 
sent between the computer and the disk: auch information is not normally 
displayed on the screen. The NOMON command allows you to disable some or 
all of this display. The command 
MOWN C p I, o 

returns the system to its usual, default state* 

If C is specified then disk commands are not displayed- If I is 
npcclfied, then Information being sent from the disk to the Apple, as 

Apple's Input , will not be displayed. If Is specified, then 
Information being sent to the disk from the Apple, as Apple's output , 

will not be displayed. 

At least one of the three parameters must be present, or NOMON is 
Ignored. The parameters may appear In any order, separated by commas. 
These parameters appear only in the commands HON and NOHON. 



MUriLU n 
Kftample: MAXFILES 6 

n Is an Integer from 1 to 16 that specifies the number of files that can 
br active at one time. tfhen HAXFILES Is executed, 595 bytes of memory 
(railed a file buffer) are reserved for each file. When you boot the 
system, n defaults to 3, so that you will have 1785 bytes reserved for 
file buffers and will be allowed a maximum of 3 files open simultaneously. 
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All DOS commands except PR#, IN* and HAXPILBS require a file buffer. Thus 
If you have HAXFILES U and oae file is OPEN, an Attempt to perform a DOS 
command (such as CATALOG) will cause the message 
NO BUFFERS AVAILABLE 
to be displayed* 




Use of MAXFILES moves HIMEM- This can erase Integer BASIC programs or 
Applesoft strings. Use HAXFILES before LOADlng and RUNning a program. 
See the discussion in Chapters 5 and 7 if MAXFILES must be used from 
within a program. 



ACCESS COMMANDS 



FP [»5s] |,Dd] [,Vvl 
Example: FP, D2 

This command puts your system Into Applesoft BASIC. Any Integer BASIC or 
Applesoft program in memory is lost* If your computer contains the 
Applesoft firmware card, DOS uses that source for the language, regardless 
of the switch position on the card. If your system does not contain the 
Applesoft firmware card, DOS attempts to load and run the program named 
APPLESOFT on the diskette in the specified or default drive. 

To place the APPLESOFT program onto a newly Initialized diskette, first 
LOAD the APPLESOFT program from the Master Diskette, then (without BUNning 
or LISTing the file) SAVE APPLESOFT on an initialised diskette. You must 
use the name APPLESOFT for this file- 

5> 

Do n« use RUN APPLESOFT to change languages. Everything looks fine at 
first, but DOS has not properly initialized the language. To avoid the 
resultant mess, always use FP. 



INT 

Rumple: INT 

This command puts the Apple Into Integer BASIC. Any Integer BASIC or 
Applesoft program in memory is lost. 



CTRL-D ( also written {CTRL )D ) 

Example: 10 D$«CHRS(4> 

20 PRINT D$;"WRITE CHESS" 
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Every character PRINTed out by the Apple is first examined by DO S be fore 
it Js sent on to the outside world. If the Apple PRINTS out a RETURN 
character (most PRINT statements automatically end with a RETURN) , and the 
neat character la a CTRL-D, this la a message to DOS that subsequent 
characters (until the next RETURN) are a DOS command* Moat DOS commands 
may he used from inside an Integer BASIC or Applesoft program. To do so, 
PRINT a string consisting of CTRL-D followed by the desired DOS command. 

The recommended way to do this Is to first create a string D$ consisting 
only of a CTRL-D, and then to use BASIC statements such as shown in the 
example. Note the use of CHRS<4) to create DS (this works only in 
Applesoft, since the CHRS function is not offerred in Integer BASIC). 
Imiti'iid, CTRL-D could btfW bean typed tfisldC quotation narks to create US, 
but in this case no character is shown between the quotation marks. 

Every character sent out by the Apple is first examined by DOS before It 

Is passed on to the outside world. If the Apple sends out a RETURN 
character (most PRINT statements automatically end with a RETURN) , and the 
next character is a CTRL-D, this is a signal to DOS that subsequent 
characters (until the next RETURN) are a DOS command. A DOS command from 

a program oust appear In a PRINT statement whose firat ouput character la 
CTRL-D and whose output Is separated from preceding and from succeeding 

printed output by RETURN'S. For additional information, see "Use of DOS 

from within a Program", in Appendix C. 



PRf a 

Example: PRfl 6 

Sends subsequent Apple output to the device controlled from slot * s * 
Instead of to the TV screen. The command 
PR# 

returns output to the TV screen. If the command Is used from inside 
program*. It must appear as a PRINTed DOS command, as shown below: 
10 DS-"": REM CTRL-D 
20 PRINT DS; "PR* I" 

If no device controller card is installed in slot 9 s » the system may 
"hang" and you'll have to press the RESET key to recover 



INf s 

Example: IN* 6 

Takes subsequent Apple input from the device controlled from slot f s , 
Inntead of from the Apple keyboard. The command 
INI 

resets the normal keyboard input. If the command is used from inside 
programs, it must appear in a PRINTed DOS command, as shown below: 
10 M* ,w l REM CTRL-D 
20 PR I NT D$; "IN* \" 

If no device controller card la installed in slot # s , the system may 
"hflng" and you'll have to press the RESET key to recover . 



157 



CHAIN f [,5a] [,Dd] [.Vv] 



Example; CHAIN PART TWO, DI, 57, VK 

Used from within an Integer BASIC proflram, it loads and runs the Integer 
BASIC program named £ on the diskette in the specified or default drive, 
but does not clear the values of any variables. This means that program 

f can operate on the results of the previous program, and can leave datn 
for any following program. You cannot CHAIN Applesoft programs using this 
command: see the special procedure for Applesoft programs in Chapter 10 or 
Appendix C. 



SEQUENTIAL TEXT FILE COMMANDS 



OPEN f l.Ss] [,Dd] [,Vvt 
Example: OPEN SESAME, D2 

Allocates a oemory buffer of 595 bytes to the text file f , and prepares 
the system to write or read from the beginning of the file- This 
command Is used with the WRITE and READ commands to create and retrieve 
sequential text files. 

If there la no file f on the diskette in the specified or default drive, 
one is created. If a file named f is already OPEN, this command first 
CLOSES that file, before OPKHing the specified file. 



CLOSE (f] 

Example: CLOSE WINDOW 

If you were WRITEing, a CLOSE causes all remaining characters in the 
output part of the file buffer to he sent to the diskette specified when 
that file was OPENed. CLOSE f deallocates the buffer associated with the 
sequential text file f • If CLOSE is used without a file name, all OPEN 
files will be closed, with the exception of the EXEC file. (There can 
only be one EXEC file OPEN at any time. When another is implicitly 
OPENed, the existing EXEC file, if any, is automatically closed) 

If a program Is interrupted by a CTRL-C while a text file is OPEN, It's a 

good idea to type 

CLOSE 

to keep any data fro* being lost. 

Files that have been allocated by an OPEN statement must be CLOSEd- 
Failure to CLOSE a file that was OPENed and written to (by a WRITE) can 
result in loss of data. 
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WRITE f l»Hb| 



Example: WRITE ADDRESS. DATA 

AIut this conmand, PRINT statements send their output to the specified 
file Instead of to the Apple's TV screen* With the Byte parameter, 
UK I TE log begins at the b-th byte of the file <see Chapter 6, page 69). 
WRITE Is cancelled by the printing of any DOS conroand, or by an INPUT 
Mat-win. The null DOS command (simply PRINTing a CTRL-D) will do. 
WRITE must be Issued In deferred-execution mode. 

After this command all Apple output characters that would normally be 
displayed on the screen are sent to the diskette instead. This includes 
INPUT question-mark prompts, error messages, and other unwanted 
characters. 



READ f (,Bbl 

Example: READ SESAME 

After this command, INPUT statements (and GET statements in Applesoft) 
obtain their response characters from the specified sequential text file 
Instead of from the Apple's keyboard. With the Byte parameter, READing 
begins at the b-th byte of the file {see Chapter 6, page 69), 

INPUT causes characters to be READ from the sequential file one field at a 
time. A field consists of from 1 to 32767 characters, ending with a 
RETURN character. However, because of the limited capacities of strings 
and input/output buffers, it is very difficult to store and retrieve 
fields of more than 255 characters. 

READ is cancelled by the printing of any DOS command* A null DOS command 
(Just PRINT a CTRL-D ) will cancel READ. The READ command must be used in 
deferred-execution mode. 



APPEND f (,Ssl l.Dd) [,Vvl 
Example: APPEND MORE INFO 

This command opens the specified text file, but places the 
posltion-in-the-file pointer to the end of the file. After this 
comowind, the next character written into the file will follow the last 
Bcquentially written character presently in the file. An APPEND must be 
followed by a WRITE to the file of the same name. (APPEND must not be 
followed by OPEN, because OPEN will reset the posltion-ln-the-f He pointer 
bach to the file's beginning.) 
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POSITION deals with a relative, not an absolute, position, since you count 
fields forward from where you are in the file when the POSITION is 
executed. 



EXEC f l,Rp) (,Sal [,Dd] 1,V V J 
Example: EXEC UTILITY 



immodiate-executioo DOS command, the command will be executed before the 
program continues. 



POSITION f [,Rp] — I ^ 

Example: POSITION ADDRESS. DATA* 8277 8? * *H 

POSITION places the posit ion-in-the-f ile pointer at the beginning of the K j J 

p-th field following the one you're In* A field Is a sequence of i ^ 

characters terminated by a RETURN. Subsequent READs or WRITEs will | 

proceed from that point In the file f* fl*-' **J 



POSITION actually scans forward through the contents of the file, 3 
character by character, looking for the p-th RETURN character. It then 

places the positlon-in-the-f He pointer at the first byte following the £L «m| 
p-th RETURN character, if, in this search. It finds any byte In which no 

character has ever been stored, the message* m 

END OF DATA i| 
is given. Normally, this occurs when the p-th field ahead of the current 

position In the file Is beyond the file's laBt entry. ^ ^ 



Similar co RUN, except that f is a text (data) file containing BASIC and ^ — t*» 

DOS commands as they would be issued from the keyboard. This allows you ^ 

to set up files that can control the Apple, isuch as you would control the ._ 

Apple yourself. jp ^JJ 

There can only be one EXEC command In effect at a time. If the EXEC file » _ 

contains the immediate-execution command EXEC, the original EXEC file Is «• " - 

closed and the now EXEC file is opened and executed. If EXEC has OPENed a 
file, the command 

CLOSE 

will not CLOSE the file being EXEC'ed. When an EXEC file has completed _ 
all its commands, it CLOSEs Itself and stops. If a file being EXEC'ed Jt^ " 

contains a command to RUN any program. EXEC waits patiently until the 

program ends. Then the next command in the EXEC file Is executed* „ 



However, if a program is running while an EXEC file is open, any INPUT 
statement in the program will take the next field from the EXEC file as 
the response. Ignoring the keyboard. Worse yet, if that response is an 
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If you type CTRL-C to stop an Applesoft program that is running while an 
EXEC file is still open, the remaining commands in the EXEC file will 
usually not be executed. p ^ 
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li ynu sprrlly the value of the R parameter* a posit ion-ln-the-f He 
pointer la placed at the beginning of the p-th field in the file, and EXEC 
will ntntt executing from this point In the file* 

An wiih POSITION, the R parameter used with EXEC should be thought of as 
thP Relative-field position parameter. However, unlike POSITION, EXEC 
tf-lyWA counts fields from the be flinninfl of your file, so p Is always 
relative to tf. The other parameters work as usual. 

II you upecKy the value of the R parameter beyond the end of the file 
you 4 1 1 get an 
KHIl OF DATA 
menma^e* 



RANDOM-ACCESS TEXT FILE COMMANDS 



OPEN f, LJ I, So] (,Dd] (,Vv) 
example: OPEN SESAME, L2 

OPEN allocates a 595-byt file buffer to the random-access text file C t 
and sets the record length to the number of bytes specified by j - The 
number j must be In the range 1 to 32767; j defaults to U 

OPHN is used with the READ and WRITE commands to create and retrieve 
random-access text flies- Note that the L (Length) parameter is not 
optional: by definition, you oust specify the record length of a 
random-access text file. Each time you use a particular random-access 
text file, you must OPEN the file with the same L parameter value. DOS 
then uses that value to calculate the starting position of any specified 
record. 

H there is oo file f, one Is created. 



CLOSE Ifl 

K<amplet CLOSE BOOK 

If you were WRITEing. a CLOSE causes all remaining characters In the 
output part of the file buffer to be sent to the diskette in the drive 
that was specified when the file was OPENed • CLOSE de-allocates the 
buffer associated vith the random-access text file f . If CLOSE Is used 
without s file name, all OPEN files will be closed, with the exception of 
an EXEC file, if any* 

If s program Is interrupted by a CTRL-C while a text file is OPEN, It's a 

good idea to type 

CLOSE 

to keep from losing data. 
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Files that have been allocated by an OPEN statement must be CLOSEd. 
Failure to CLOSE a file that was OPENed and written to (by a WRITE) can 
result In loss of data. 



WRITE f (,Rr] [,8b] 

Example: WRITE ADDRESS. DATA, R3 

After this statement, PRINT statements send their output to the specified 
file instead of to the Apple's TV screen. WRITE la cancelled by the 
printing of any DOS command* or by an INPUT command- The null DOS command 
(simply PRINTlng a CTRL-D) will stop a WRITE with a minimum of effort. 
WRITE can be used only in deferred-execution PRINT statements. 

The R (Record) parameter causes the WRITE to begin at the first byte of 
the r-th record, where each record contains the number of bytes, j , 
specified by the L parameter given with OPEN. r defaults to 0* If 
the R parameter is specified, the WRITE will begin at the b-th byte of 
the r-th record in the file* 



After the WRITE statement, all Apple output characters that would 
normally be displayed on the screen are oent to the diskette Instead . 
This includes INPUT question-mark prompts, error messages, and other 
unwanted characters. 



READ f !,ftrj [,BbJ 

Example: READ SESAME, R3,B30 

After this statement, INPUT statements (and GET statements in Applesoft) 
obtain their response characters from the apecified random^access text 
file Instead of from the Apple's keyboard. INPUT causes characters to be 
READ from the random-access file's current record, one field at a tim*. 

A field can be from 1 to 32767 characters, ending with a RETURN character. 
However, no record should be more than j characters in length, where J 
is the record length specified when the file was OPENed * 

The R (Record) parameter causes the READ to begin at the first byte of the 
r-th record, where each record contains the number of bytes, J , 
specified by the L parameter given with OPEN. r defaults to 0. If 
the B parameter Is specified, the READ will begin at the b-th byte of 
the r-th record in the file. 

READ is cancelled by the printing of any DOS command. A null DOS command 
(Just PRINT a CTRL-D) will cancel READ. 
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MACHME-LANGUAGE FILE COMMANDS 



HSAVE f, Aa, Lj [,Ss] [,Dd| [,Vvl 

Examples: BSAVE PICTURE, A16384, L8192 
BSAVE PICTURE, A54000, L52000 

Creates a file named f , and stores the contents of a segment of the 
APPLE Il's memory. The segment Is specified by the starting address a , 
and the number of bytes to be stored j . 

The examples shown above store a high-resolution picture, from the second 
high-resolution picture area. They are operationally identical: the 
second example just uses hexadecimal notation for the parameters. 



BLOAD f l,Aa) t,Ss] [,Dd] (,WI 

Examples; BLOAD PICTURE, A8192 
BLOAD PICTURE, AS2000 

If a Is not specified, then BLOAD places the specified file in Apple's 
memory beginning at the starting location of the memory area that was 
originally BSAVEd. If a is specified, then the data Is placed in 
Apple's memory beginning at address m » Note that a machine-language 
program may no longer be executable if so moved. 

Assume that a a high-resolution graphics picture has been BSAVEd on a 
diskette under the file name PICTURE. Then the first example shown above 
would place the picture into the first high-resolution picture area, which 
starts at memory location 8192 (decimal). The second example la 
equivalent: the address is shown in hexadecimal, as Indicated by the n $" 
before the 2000. 




Either example would clobber any version of Applesoft that Is not in 
firmware. 



BRUN f LAal [,SsJ [,Dd] l,Vv] 
Example: BRUN SUPER, A$C0A, V75 

B]*OADs the file f Into Apple's memory beginning at location a . If the 
A parameter is omitted, the file is BlAADed starting at the same 
location from which it was BSAVEd. Once BLOADed, the file (which should 
be a machine-language program) is started by a machine-language Ju»p (*IMP) 
to location a » 
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This appendix contains summaries of the main procedures used in DOS. Each 
procedure is listed on Che prcceedlng contents pap;e, Along with the page 
number on which it appears. 

BOOTING DOS 

Replace "s" by the slot number In which the disk controller 1b located. 

Prompt To boot DOS, 

Character Language type 

> Integer BASIC PH*s or 1Mb 

] Applesoft PR(s or INffa 

* Monitor s{CTRL)P 



INITIALIZING A DISKETTE 

To INITialUc a slave (memory dependent) diskette: 

1) Boot DOS 

2) Insert a blank diskette into the disk drive 

3) Type In a greeting program, e.g. 

10 PRINT M 32K SLAVF DISKETTE INITIALIZED 5 MAY 80" 
29 END 

4) Assuming you choose to name the greeting program "HELLO", 
type the command 

INIT HELLO 

5) After the IN USE light on the disk drive goes out, rerove 
the diskette and label It. 

To make a master diskette, use the MASTER CREATE program, page 4A. 



RECOVERING FROM ACCIDENTAL RESETS 

If DOS has been hooted and dhen the RESET (try is accidentally pressed, type 
3D0C 

(that's the numeral zero after the D) to get back into the BASIC you left 
with your program intact. 



USE OF DOS FROM WITHIN A PROGRAM 

DOS commands may be issued from within a program by PRINTing CTRL-D then 
the command. First create a string DS which consists only of CTRL-D. 

In Applesoft, D$ way be created hy the command 
DS ■ CHR5(«) 

since CTRL-D is the character whose ASCII code ie 4. 
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In either BASIC, DS may be defined by typing 
DS - " 

(hen holding down the CTRL key while typing the letter D* and then typing 
the closing quote. Control characters such aa CTRL-D aren't displayed, so 
what you'll see la 
DS - "" 

This Applesoft program displays the CATALOG when RUN: 

3 *** Gff£E?tr*& P*OCtf?flh 

iG IV* * £»«» <4> WEM CT*L-# 

2ft i*KlHT f>*- "CRlflt-OG* 
Only one DOS command may be contained in a single PRlffT statement. The 
PRINT statement's quoted contents must begin with a CTRL-D and end with 
the DOS command- The CTRL-D must be preceded by a RETURN (sent 
automatically at the end of most PRINT statements). 

These commands should only be used in deferred-execution mode (from within 
a program), appearing after CTRL-D In a PRINT statement: 
OPEN APPEND READ WRITE POSITION 

The commands INIT and HAXFILES are best used only in immediate-execution 
mode (not from within a program). 

Other DOS commands may be used either in immediate-execution mode, or from 
within a program where they appear after a CTRL-D in a PRINT statement. 



CREATING A TURNKEY SYSTEM 

To make a diskette that runs a certain program each time the diskette Is 
booted ™ in the example we will use the program COLOR DEMO — use the 
following procedure: 

1) IHITlallze a blank diskette, using the name HELLO for the 
greeting program. 

2) Place a disk containing the COLOR DEMOS program in drive* 
and type 

RUN COLOR DEMOS 

Once you're satisfied the program RUNs correctly* return 
to BASIC. 

3) Put the newly INITialized diskette into your drive and type 
SAVE HELLO 

to replace the old greeting program by the COLOR DEMOS 
program* 



CREATING AND RETRIEVING SEQUENTIAL TEXT FILES 

When creating a sequential text file, an OPEN must precede a WRITE; once 
WRITE is executed, any subsequent PRINT comnands send all characters to 
the diskette. CLOSE the file when you're done. A WRITE command i» 
cancelled by an INPUT or the use of any DOS cocanand in a PRINT statement 
— even just PRINTlng CTRL-D will do* 
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This Applesoft program creates a sequential text tilm named SAMPLE whoae 
first thirteen fields contain three strings and the Integers 1 through 10: 

S KOt MM SAMPLE 

i» d« * chpm <4> sen cnrL~l> 



2» 


PRINT 


0». -OTCN SflMPUf- 


3© 


PRINT 


Pfc "DELETE SAMPLE- 


40 


PRINT 


P»- 'ORtN Sf^Lf" 


SO 


PRINT 


D»; "WRITE 5flm_£* 


ce 


PRINT 


"HI MO": PRINT "HI W 




PRINT 


"OFF TO THE DISK HE 00 


S* 


FOR J 


» 1 IO i» 


-.. 


PRINT 


J: J 



lie PRINT 09- 'CLOSE SflHPUS* 

If you OPEN a file that already exists and then WRITE to it f you will 
overwrite part of the original file. 

This Applesoft program retrieves the file SAMPLE described above, one 
field at a time. If you wish to aee what Is being HEAD from the disk, the 
eottmand 
HON I 

will cause Input froa the disk to be displayed* 

IS CTRL-* 

» PPINT Ma -OPEN SAMPLE* 1 

3* PRINT 0*> H BC«> SfWLE" 

48 INPUT Aft. B*, Ct 

50 POP? I » i TO 10 

60 iNPirT M 

7» NEXT Z 

W PRINT 0* "CLOSE SftMPLC* 

An OPEN must precede a READ* Once a READ is executed* any subsequent 
INPUT statements (in Applesoft, CETs also) obtain their response 
characters fro* the diskette instead of from the Apple's keyboard* CLOSE 
the file when you're done. 

A READ is cancelled by PRINTing CTRL-D, whether or not it's followed by a 
DOS command. 
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ADDING DATA TO A SEQUENTIAL TEXT FILE 



This Applesoft program adds the two strings "TEST 1" and "AND HOW FOR TE5T 
2" to the end of a sequential text file called SAMPLE. Each string la In 
an additional field of the file. 

•> IHEfl RPPENP 1W£ 

M t>» - CHR» «M CTHL-f 

30 PRINT [)*, "APPEND SWPL£° 

3» PRIWT !-f ■ "URI te ami" 

«0 PRINT "TEST 

W PR J NT r*3W FOR TEST 2" 

PRINT 0», -CtOSfi SRHPLE" 

CONTROLLING THE APPLE VIA A SEQUENTIAL TEXT FILE 

When RUN, this Applesoft program creates a text flic named DOIT containing 
the commands 

LIST 29.59 
RUN HELLO 
CATALOG 

3 REN MME DOIT 

\0 . CM*?* t*>: REM CTKLH> 

2«l PRINT D». "0P£-N DOIT" 

5© PRINT 0». "fcRITE DOIT" 

PRINT "LIST 2*< 5»" 
«*■ PRINT "R<_« MELtO" 
6¥» PRIWT '■CATALOG* 

pr-int t*». -close dost- 

Once the text file DOIT la created, the command 
EXEC DOIT 

will cause the commands In the file DOIT to be executed one by one. Just 
as if they'd been typed in from the keyboard. 
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CREATING AND RETRIEVING RANDOM — ACCESS TEXT FILES 



This Applesoft program creates a random-access text file named RA-FILE, 
whoae records are each 30 bytes long. Then it WRITP.s the string "NAME 
ADDRESS" followed by the record number. Into records 12 through 15 of the 
file. In lines 70 and 80, record number 13 is changed to contain the 
string "DOS". 

£0 Pffl-VT ti*^ "OPEN Pf*~FIL£' 

ffirmt C* 'OPEN Wfl-Pii.e-l.36'' 
5* FC» I = 12 TO 13 
£tf WtWT 0*t "WRITE flfVF JLE.(?-*I 

M **WT C'*-'*W#>ITC Rf4-fIL£- RiJ" 

This Applesoft progran READS records 12 through 15 of the random-access 

text file RA-FItE. Note that you must specify each record before RFADinR 

It In lino 40. Line 60 examines the three leftmost characters of the 

input string AS, taken from each record. If those three characters are 
"DOS", the message "RECORD r UAS CHANGED." Is PRIWTed, and the search 
continues. 

5 REM RETRIEVE Fft-FILE 

18 5* * CW>* <4f REM CTRL-0 

251 Wt«fT c*«< "OP'EN Rft-^ILE* LSO" 

*J& . : * TO t» 

«# P*IWT $fe Kft-MUf- R"-J 

e» IF LEF T* '.'ft*. 3.3 ■ 'DOS" THEN 

wtr*it "Becoafii m :ji n «fts CHfw 

iKO. * 

ee ppint d#. -close iu- 
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COPYING A TEXT FILE 



Moving a BASIC or a binary program file to another diskette la no problen: 
Just LOAD or BLOAD the file's contents Into the Apple, and then SAVE or 
RSAVE those contents back onto the other diskette. Remember to specify 
the starting address and length parameters when using the BSAVE command. 

The COPY program allows you to bulk copy the contents of one diskette onto 
another- If any of the files on the original diskette are protected fron 

copying* you'll get an error message: 

I/O ERROR 

STOPPED AT 320 

To copy a text file, or any unprotected file for that Batter, use the FID 
program* The full instructions for using FID are in Appendix J. 

CHAINING IN APPLESOFT 

To REN a series of Applesoft programs without erasing earlier values of 
variables and arrays use the following procedure* 

Suppose you wish program PART ONE to chain to the prograa PART TWO. 
First, make sure the binary file CHAIN ia on the same diskette with the 
program PART TWO. (If it isn't, use FID to copy it onto the right place.) 
Then simply insert these two lines as the 
last two lines to be executed in the PART OWE prograa: 
PRINT CHRS(4); "BLOAD CHAIN t A52fl H 
CALL 520"PART TWO** 

No space or other character may be between the and the m 
in the CALL command. 
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If you already have a Disk Operating System, and are usinft .1 version of 
DOS that runs in 13 sectors, (DOS 3*2*1 or earlier), you will need to 
change two proras on your disk controller card to update your system to 16 
sectors* Any version of DOS earlier than release 3-3 will need to be 
updated * 

HOW TO INSTALL THE NEW PROMS 

The new disk controller PROMs replace two PROMs on each Disk II controller 
card in your Apple- 
Inside the case, find the edge-connector "slots" at the rear of the main 
board- In one or more slots you will find cards labelled 'Disk II 
Interface Card' at the top edge* Hake sure the power is off* Remove each 
of these controller cards by grasping it at the top edge and gently 

rocking it back and forth. Remove the ribbon cables from each card, so 
you can work on it ©ore easily. 

Hold a controller card in one hand, IC side toward you, "fingers portion" 

down* You will see four rows of two ICs on the card. Find the left IC In 
the second row from the top* It should be marked 'P6' or '341-00 1 0-MC J 

(possibly under a copyright sticker), and the card below it should be 
marked 'PROM P6'* This is the IC you will replace with the new PROM P6A. 

Now find the left IC in the bottom row. It should be marked 'P5' or '341* 

xx* (possibly under a copyright sticker), and the card below it 
should be marked 'PROM P5*. This is the IC you will replace with the new 
PROM P5A. 
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Now look at the new PROMs. The new PROM P6A should be marked 'P6A' or 
*)61-f028-xx', or both. The new PROM P5A should be marked 'P5A* or '341- 
fl027~xx', or both. You should be able to find these markings without 
peeling off any stickers. If you can't find the numbers at all, see your 
dM ler. 

Now that you know where everything is, you are ready to replace the old 
PROHs with the new ones* Set the controller card down on a table and hold 
it firmly. Using the IC puller, gently remove PROM P6 from its socket. You 

may find a translator, marked 'Q3' on the card, blocking the IC puller. If 
ho, gently bend It out of the way until it is approximately vertical- 
Grasp the IC with the puller, and gently rock it out of its socket. 

Hold PROM P6A, marked 'P6A' or ' 341-M28-xx', so that It faces the same way 
as the ICs on the card. The large rectangular notch should be on the left 
side as you face the card* (There may be a small circular depression on 
the other end. If you are not sure which end goes where, ask your dealer*) 
Making sure that each pin lines up with its hole, gently insert PROM P6A 

into socket P6. If the pins are too widely spread to go in easily, you may 

have to bend them in until they are vertical, by pushing them carefully 
(gent vl against a table top. 

Now remove PROM P5 and replace it with PROM P5A, marked 'P5A' or '341-0027- 
xx', Just as you replaced P6 with P6A. 

If you have more than two Disk II drives, you will need one controller card 
for each two drives* Each of these cards will need the new PROMs. Install 
these as you installed the first pair* 

MULTIPLE DISK DRIVES 

Now connect each Disk II drive to its controller card and plug the card 
Into its slot. In the order shown in the table below. The first drive 
should go in the first location listed (slot 6, drive 1), and so forth, 
until you have Installed all your drives. You will be working downward 
( ton slot 6. filling first the drive 1 and then the drive 2 connectors of 
each card. This will ensure that the drives are in the most efficient 
locations, and will increase the reliability of your system: programs will 
not try to use drives that are not there, or ignore drives that are there. 

Placement of Disk II Drives 



Installation Slot No. Drive No. 

Order 

1st drive 6 1 

2nd drive 6 2 

3rd drive 5 1 

4th drive 5 2 

5th drive 4 1 

6th drive 4 2 



Label each drive 'DRIVE I' or 'DRIVE 2', as appropriate- 
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Check that all connections are secure and that everything has been 
installed in its proper place- PROM P5 of each controller card should 
have been replaced by PROM P5A (3&l-W27-xx). PROM P6 of each controller 
card should have been replaced by PRCW P6A (341-M28-ocx). A Disk 11 
ribbon cable should be plugged into the drive 1 connector of each Disk II 
controller card. Slot 6 should have a controller card- 
When you are satisfied that everything is installed properly, you can 
replace the Apple's cover and go on to update your existing 13 sector 
diskettes to 16 sectors* using MUFFIN* 

USING DOS WITH THE LANGUAGE SYSTEM 

You can use DOS and both Applesoft and Integer BASIC with the Apple 
Language System installed. You do not need the BASICS Diskette to do this. 
To begin a 16 sector DOS after using any language on the Language System 
which uses the Pascal Operating System, follow these steps: 

1) Be sure to save any progran you have been working on. Otherwise, It 
will be erased from memory when you begin DOS* 

2) Get into the Command mode of the Pascal Operating System (so chat you 
can see the line which begins with "Command : "> . 

3) Replace the diskette in your Drive 1 (connected to the controller card 
in your highest numbered slot) with the DOS System Master diskette. 

4) Type H (for Halt). Thia will cause that disk drive to boot your System 
Master diskette- 

Your System Master diskette will now load either Applesoft or Integer BASIC 
— whichever is NOT already available on your main board — into the 
storage space available on your Language Card. If you have a standard 
Apple II, the System Master* when booted, will load Applesoft into your 
Language Card. If you have an Apple II Plus, Integer BASIC will be 

loaded* In either case, a message will appear, telling you which BASIC is 
being loaded during the booting of your System Master. All of the DOS 
commands will now work in the using and writing of programs in both 

Applesoft and Integer BASIC. 

To learn the procedure for starting DOS after using a language which does 
WOT use the Pascal Operating System, see the manual for that language. 

With the Language System installed, you can boot DOS upon turning on your 
Apple, with the System Master diskette in Drive 1. 

To return to another Language System language from DOS, replace the System 
Master in Drive 1 with the startup diskette for that language. Then type 
PRflfi and press RETURN. 
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SETTING UP A TURNKEY SYSTEM 



When you insert a DOS 3-3 diskette in drive 1 and turn on the power, your 
Apple will run the HELLO program on that diskette, if it has in RCM the 
BASIC In which the HELLO program is written. That is, an Apple 11 will run 
an Integer BASIC HELLO program, an Apple II Plus will run an Applesoft 
HELLO progran, and an Apple II with the Applesoft Card or an Apple II Plus 
with the Integer BASIC Card will run a HELLO program in either BASIC* If 
you don't have that BASIC in ROM, you will get a 
LANGUAGE TOT AVAILABLE 

error message and the prompt for the BASIC it does have. 

If you have the Apple Language System, things get a bit more complicated. 
Without further ado, you can run programs in the BASIC in ROM, but before 
you can use the other BASIC, you must load it into the Language Card. The 
simplest way to do this Is to boot the DOS 3-3 System Master Diskette, 
which Is provided with two programs, HELLO and APPLESOFT, that together 
make sure that both BASICs are loaded when you boot DOS. HELLO, written in 

Applesoft for the Apple II Plus, loads Integer BASIC. APPLESOFT, written 
in Integer BASIC for the Apple II, loads Applesoft. Your machine will run 
the appropriate program, and afterwards behave as if it had both BASICS in 

ROM. You can now insert any other DOS 3<3 diskette, and run any program on 
It. 

If you wish to make a diskette that will boot on all systems, 

and load the Language Card If necessary, you can do it by copying the 

appropriate files onto it* Here's how: 

L. Boot the DOS 3-3 System Master Diskette* 

2. LOU) HELLO from the System Master, then insert a blank diskette and 
type 

IN IT HELLO 

3. When INIT is finished, reinsert the System Master, BRUN MASTER 
CREATE and type 

HELLO 

when asked for the nave of the greeting program. Insert the blank 
diskette when told to do so by MASTER CREATE. 

4. Using FID, copy these files onto your newly initialized diskette: 
APPLESOFT 

INTBASIC 
FPBASIC 

5. Put any programs and other files you want on this diskette. Make 
sure you have at least the following files: 

HELLO 
APPLESOFT 
INTBASIC 
FPBASIC 

When you boot this diskette on an Apple with the Language Card, it will 
load the Language Card with the BASIC not in ROM, so that the Apple can 
run any program in cither BASIC* 
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If you have a turnkey program you want the Apple to run when it Is turned 
on, you can do it by changing the HELLO and APPLESOFT programs so that each 
of them will run your turnkey program (we'll call it TURNKEY here)* You 
will find It easier to edit these programs if you first RUN LOADAPA. then 
use the £S command, so that you can see the CTRL-D in each embedded DOS 

Start with the diskette you have just made in steps 1 to 5> and do the 
following: 

6* UNLOCK HELLO 
7. LOAD HELLO 

8* LIST It and look at the last few lines 
260 END 
250 REM 

260 REM —NO CARD OR CAN'T RELOAD 
270 RIM 

280 IF PEEK (768) - THEN END 

290 PRINT: PRINT 11 * . .LANGUAGE CARD CANNOT BE RELOADED": 

PRINT " UNTIL THE SYSTQ1 IS REBOOTED.-." 
300 END 

On the screen, the lines will be wrapped at 40 characters; here 
they are broken elsewhere for clarity* 

9- Change these lines so they read as follows: 

* 240 GOTO 300 
250 REM 

260 REM — NO CARD OR CAN'T RELOAD 
270 REM 

* 280 IF PEEK (768) - THEN 300 

290 PRINT: PRINT "...LANGUAGE CARD CANNOT BE RELOADED": 
PRINT " UNTIL THE SYSTEM IS REBOOTED*.." 

* 300 PRINT "ctri-dRUN TURNKEY" 

The lines changed or added are marked with asterisks. The lower case 
Ctrl- d in line 300 represents a CTRL-D which won't show up on the 
screen or In a listing. If you don't like invisible control characters 
in your files, you can declare a string D$ containing a CTRL-D, which 
would sake line 310 look like this (in Applesoft): 

* 319 D$-CHR$(4) : PRINT D$;"RUN TURNKEY" 

If you do this, make sure you declare D$ before you use it. 

You may also wish to change or delete some of the PRINT statements in 
the program, but make sure you leave the ones with DOS commands {these 
will have CTRL-Ds in them). 

10. SAVE HELLO 
II- LOCK HELLO 
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12. UNLOCK APPLESOFT, LOAD it* and LIST it, looking at the last few 
lines* 

250 GOTO 310 
260 REM 

270 REM —HO CARD OR CAN'T RELOAD 
280 REM 

290 IF PEEK (768) - THEN 310 

300 PRINT "...LANGUAGE CARD CANNOT BE RELOADED": 

PRINT " LNTIL THE SYSTffl IS REBOOTED..." 
310 PRINT "ctrl-dINT" 



13. Change these lines to read as follows: 
250 GOTO 310 
260 REM 

270 REM —NO CARD OR CAN'T RELOAD 
280 R&l 

* 290 IF PEEK (768) - THEN 310 

300 PRINT "-..LANGUAGE CARD CANNOT BE RELOADED": 
PRINT " UNTIL THE SYSTEM IS REBOOTED..." 

* 310 PRINT "ctrl-dRUN TURNKEY" 

Line 310 can also be put In the fom 

* 310 D$-"ctrl-d":PRINT D$;"RUN TURNKEY" 
to nake the CTRL-D easier to find. 

U. SAVE APPLESOFT 

15. LOCK APPLESOFT 



16. RENAME your turnkey program TURNKEY. A sample TURNKEY program, in 
Applesoft* is below: 

100 TEXT : HOME 

110 VTAB 3: PRINT "DOS TOOL KIT "; TAB( 30) ;"30 NOV 1979" 

120 VTAB 5: PRINT "(C) COPYRIGHT 1979, APPLE COMPUTER INC." 

130 FOR I « 1 TO 1500: NEXT I 
140 PRINT "ctrl-dRUN RIBBIT" 

17. Make sure your diskette has the following files on it: 
HELLO 

APPLESOFT 
INTBASIC 
FPBASIC 
TURNKEY 

18. Now test your turnkey diskette by putting It in drive 1 and 
turning the power off and on. It should boot DOS 3.3, then load 

Integer BASIC or Applesoft if necessary, then run the program 
named TURNKEY. 
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APPENDIX I 



HE BASICS DISKETTE 



142 Sooting DlakottM by Ming "BASICS' 





The BA5ICS" diskette that came with the DOS system master can be used to 
boot 13-sector diskettes on your 16-scctor system. Versions of DOS 
earlier than 3*3 are 13-sector DOS* 

Apples come in two flavors: Apple II and Apple II Plus* The Apple II has 

Integer BASIC in Read-Only Menory (BOH) on the main printed-circuit bo/ird. 
The Apple II Plus has Applesoft BASIC in ROM on the main board* The 

language In ROM Is the language the Apple will come up in when it is turned 

on* If it has no disk drives or accessory cards. 

BOOTING DISKETTES USING "BASICS" 

To use either Integer or Applesoft BASIC, insert the "BASICS" diskette into 
the drive, and turn the Apple on* In about five seconds the screen will say 

ikscitt your i£~secTOR diskette 

Insert any 13 sector DOS /BASIC diskette and press RETURN * The Apple will 
now behave as described in this Manual, except that one step Is added to the 

boot (startup) procedure; 

Vhen you turn the Apple on. or type PR#6. 1W#6, C600G, or 
6CTRL-P, the "BASICS" diskette must be In the drive, each tlae 
you want to boot a 13 sector DOS. 

When the cue comes on the screen, insert the 13 sector DOS/BASIC diskette you 
wish to boot* if you are in either BASIC and you type PR#6 or IN#6 . you 
will have to insert "BASICS", then reinsert your previous diskette. 

Once you have DOS running, you can switch from one BASIC to the other by 
using the INT and FP commands normally* 

As always, you can tell which BASIC you are in by the proapt you sec on the 
acreen: > for Integer BASIC and 1 for Applesoft BASIC* 

A diskette designed for "turnkey" operation (that is* one that starts 
executing a program when booted) can he run as before, after the "BASICS" 
diskette has been run* 

You can reboot DOS without turning the power off. Simply insert "BASICS", 
type PR#6 or IN#6 and press RETURN . then at the cue insert the 
diskette you wish to boot* 
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FID PROGRAM 



IB* Starting Bp 

Fli-Humta and Ulidcfl 

185 Com* tula 

186 tUroz Handling 



FID (for File Developer) extends the abilities of 16-sector DOS In two 

ways- First, it lets you easily catalog, copy, delete, lock, and unlock all 
types of DOS files. Second, It lets you copy from one diskette to another 
with only one disk drive* 

FID runs on any Apple with Applesoft, 32K or core of memory, and one or 
more Disk II drives* The FID destination diskette (the one you will he 
copying to) must be initialized in order for FID to work. 

STARTING UP 

To use FID, boot the DOS System Master Diskette, then type 
BRUN FID 

You will see a list of commands on the screen. Each of them can be 
executed by typing the number in angle brackets < >• 

FILENAMES AND WILDCARD CHARACTERS 

Some of the commands ask you for a filename* The filename is typed just 
as for a DOS command, except chat you can replace part of the filename 
with the "wildcard" character ( - ). For example, If you typed the 
filename 
FR-ED 

the program would select all the files whose names began with 'FR' and 
ended with *EP* ■ If you typed 

all files whose names contained 'N* would be selected. If you typed 

all files on the diskette would be selected. ("On which diskette?", you 
might ask. This will he explained below.) 

If you used a wildcard character in a filename specification, you wilt be 
asked 

DO YOU WANT PROMPTING? 

If you reply by typing 
Y 

for Yes, you will be asked to verify each filename before it is acted on. 

If you want the file, when the system displays It on the screen, type 
Y 

If you don't want the file, type 
N 
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* -4 

*= H 

** -4 

E 4 

£ 4 

m 4 

W 4 

B 4 




In cither case, you will then be prompted with the next filename matching 
your specification. 

If you don't want the file or any of the rest, type 

Q 

and no more files will be acted on. 

If yon reply 
N 

to the 'DO YOU WANT PROMPTING?', all files matching your 
specification will be selected. 

COMMANDS 

Host of the FID commands — Catalog, Space, Delete, Lock, Unlock, and Verify — 

operate on one drive: the one last used, unless the defaults are reset. 
The Copy command can use one drive or two, as you wish- The Quit command 
does not use the drives: it simply exits the program, leaving you in DOS- 

When the program first comes up, no default drive will have been set* If 
your first command is one of the one-drive commands — Catalog, Space* 
Delete, Lock, and Unlock — you will be prompted for a slot and drive 
number. These will set the default drive until they are changed* If your 
first command is the Copy command, you will be prompted for two sets of 
slot and drive numbers, one for the source and one for the destination. 
Any time you switch from Copy to a one-drive command, or vice versa, you 
will be asked to specify one or two drives. With the Reset command, you 
can cancel the default slot and drive numbers at any time, which will cause 
FID to prompt you for new ones when it needs them. 

Note; make sure you give real slot and drive numbers: if the Apple tries 
to read from or write to a nonexistent drive, the program will crash. 



CATALOG 

Typing 

2 

gives you a catalog of the default diskette* If you have not set the 
defaults, you will be prompted for slot and drive numbers. Once these 
have been set, all commands will automatically refer to this drive, unless 
the defaults are reset. 



RESET SLOT AND DRIVE 

The Reset command lets you change the 

type 

J 

This cancels the current default slot 

give a command that requires slot and 
for them* This command is convenient 

■uccvwlon* 



default slot and drive. To use it, 

and drive numbers. The next time you 
drive numbers, you will be prompted 
if you wish to Catalog two drives in 
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Note: The Reset Slot and Drive command should not be confused with 
the RESET key. They will always be capitalized differently, to avoid 
confusion- 



LOCK FILE 

To lock 3 file, type 
5 

and, when prompted, type the filename* If you type an invalid filename, 
you will be prompted until you give a valid one* 

You will now be asked to Insert the diskette containing this file, and 
asked whether you wish to ESCape or proceed- If you proceed and the file 
is on the diskette inserted, it will be locked- When you catalog the 
diskette, the filename will be preceded by an asterisk , * , Indicating 
that the file is locked* If the file is not on the diskette, you will get 

a NO FILES SELECTED error messsge: you can recover by pressing any key 
except RESET, SHIFT, CTRL, or ESC. 

UNLOCK FILE 

To unlock a file, type 
4 

and, when prompted, type the filename. If you type an invalid filename, 
you will be prompted until you give a valid one. 

You will now be asked to Insert the diskette containing this file, and 

asked whether you wish to ESCape or proceed. If you proceed and the file 

is on the diskette, it will be unlocked. When you catalog the diskette, 
the filename will not be preceded by an asterisk , * , indicating that the 

file is not locked. If the file Is not on the diskette, you will get a NO 
FILES SELECTED error message: you can recover by pressing any key except 
RESET, SHIFT, CTRL, or ESC- 

VERIFY 

The Verify comaund is the same as the DOS VERIFY command, and handles all 
types of files. To use it, type 

and answer the prompts. When a file has been verified, the screen will 

display its name and the word 

DONE 

If a file can't be read and Is thus invalid, you will get an I/O ERROR 
message, and the program will prompt you to press a key. When you do so, 
you will return to the main menu. 
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COPY FILE 

FID ran Copy files on either a multiple-drive or a single-drive system. To 
Copy f lies, type 
] 

and you will be prompted for Source slot and drive numbers, then 
Destination slot and drive numbers. 

Multiple-Drive Copying 

If the slot and drive numbers are different, you will be asked for a 
lllenaae, which can contain wildcard characters. You can copy a whole 
diskette by typing • In response to this prompt- After you have given the 
filename, you will be asked to Insert the appproprlate diskettes and press 
either ESC, to abort the Copy, or any key but RESET, SHIFT, CTRL, or ESC, 
to go ahead. If the files you asked for are on the source diskette, and if 
there is enough room for them on the destination diskette, then you will be 
informed that your file has reached its new home; otherwise, you will get a 

DOS error message. 

If the destination diskette already contains a file with the name you 
used, you will get the message 

FILE 

ALREADY EXISTS. 
TYPE IN NEW FILE NAME FOR THE COPY OR 
<RETURN> TO REPLACE PRESENT FILE OR 
<CTRL-CXRE1URN> TO CANCEL COPY 

: 

If you enter a new filename, the file will be transferred and stored under 

that new name. If you press RETURN * the old file will be replaced by the 
new one, if the old file Is not locked. If it Is, you will see 

FILE LOCKED. 

DO YOU WISH TO REPLACE IT ANYWAY? 

If you type 
Y 

the file will be replaced; if you type 
N 

you will get this message again: 
FILE 

ALREADY EXISTS* 

TTPB IN NEW FILE NAME FOR THE COPY OR 
< RETURN > TO REPLACE PRESENT FILE OR 
<CTRL-C><RETURN> TO CANCEL COPY 

: 
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If, when you see this message, you press CTRL-C and then RETURH, the file 
will not be copied- If no files were found to copy, the program will print 

NO FILES SELECTED 

If a file was found, the program will print 
DONE 

Then you will be prompted: 
PRESS ANY KEY TO CONTINUE 

Pressing a key will return you to the menu. 
Single-Drive CopyinR 

If the specified slots and drives for the source and destination are the 
same, the program will tell you when to put the source and when to put the 
destination disk into the drive. Thus, copies can be made between two 
disks with only one drive. 

DELETE FILE 

This command deletes a file or set of files from the default diskette. 

To use it* type 

6 

You will be asked 
FILENAME? 

When you type the filename, the program will try to delete the named 
file. If all goes well, you will see the message 

<DONE> 

on the screen. If the file could not be found, you will get the message 

NO FILES SELECTED 

If the file was locked, you will get the message 
FILE LOCKED 

and the file won't be deleted. 

To return to the menu, press a key other than RETURN, ESC, CTRL, SHIFT, or 
RESET when you see the prompt 

PRESS ANY KEY TO CONTINUE 



SPACE ON DISKETTE 



This command lets you find out how many sectors are used, and unused, on 
the default diskette. To use it, type 

1 

and those numbers will be displayed on the screen. 



This command lets you exit the program cleanly. When you type 

you will see the same prompt on the screen as you saw before you ran FID. 



ERROR HANDLING 

If the program detects an irrecoverable error, it will display an error 
message and abort the operation- If a Copy operation is aborted, you 
should catalog the destination diskette and delete any spurious file that 
may have been created by the operation* This spurious file, if it exists, 
will have the name of the original file, or a new filename if you gave it 

one, but it will be shorter than the original file, as it will be 
i ncomplete* 

Error messages are generated for these errors: DISK FULL, DISK WRITE 
PROTECTED, FILE LOCKED and I/O ERROR. If one of these occurs, FID will 
wait for you to press a key. then return you to the main menu* 

If a DOS error other than one of these occurs. Its error code number will 
be printed. This will happen only if you clobbered DOS. or clobbered FID, 
or tried to copy a BAD FILE. If any of these things happened, you should 
reboot DOS, and reBRUN FID. 

If an error causes a spurious file to be placed on your destination 
diskette, delete that file immediately, before copying any other files to 
the destination diskette. 
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MUFFIN PROGRAM 




APPENDIX K 



192 ftcartia* Bp 
192 Wildcard Cbaractar* 




The current DOS is a "16 sector" DOS* Earlier versions of DOS Are 13 

sector- For a discussion of sectors, see the section entitled "Overview of 
the Storage Procesa" In Appendix C* 

A 16 sector DOS will not work vlth diskettes that have been THITialUcd 
with a 13 sector DOS* This Is because the information Is arranged 
differently on a 13 sector diskette* If you try to use 13 sector diskettes 
vlth a 16 sector DOS. you'll see the message 
UNABLE TO READ/WRITE 



STARTING UP 

The MUFFIN program converts 13 sector diskettes, and the programs they 
contain, to 16 sector* It does this by rearranging the Information and 

then writing it onto another diskette* The diskette it writes the 
information onto (the "destination") oust have been INITialized with a 16 
sector DOS* After the Information from the old diskette (the "source") is 

converted onto the destination, the 13 sector version of it will still 
exist on the source diskette- 

To maximize the amount of disk space which is usable by this DOS, it's best 

to convert all your 13 sector files to a 16 sector diskette and then re- 
INITialixe the old diskettes with the current DOS- 

The MUFFIN program will work with either one or two disk drives- 

This example shows how to use MUFFIN to convert files from a 13 sector 

diskette onto a 16 sector diskette, on an Apple with one disk drive* 1c 
assumes your disk drive is connected to the controller card In slot #6. 

1) Place the System Master diskette in your drive and typo 
BRUH MUFFIN 

2) When the message 

* APPLE X DOS 3 2 TO 3- 3 CONVERTER * 
m m 

* MUFFIN VERSION D ♦ 

* • 

* CGPVKIGHT 1979 APPLE COMPUTE* INC * 

***** ***■*■ »***»**»**********■*♦* ****** *** 

CHOOSE Oft OF THE FOLLOWING OPTIONS 

Cl> CONVERT FILES 

<2> 001 T 
WHICH WOULD VOU LIKE? 

appears, type 
I 

to Indicate that you wish to convert files* 



192 



3) Nov you'll see the question 
SOURCE SLOT? 

Type 6 (the number of the slot your disk controller card Is in)- To the 
next question: DRIVE? respond with I- 

ft) When you see 

DESTINATION SLOT? 

type 6, and then answer the question DRIVE? by typing I* 

5) Now you'll be asked for the name of the file to be converted: 
FILENAME? 

Type ■ (an equals sign) here. The ■ is a symbol which represents the 
names of all the source diskette's Mies, This response means that you 
wish to convert the entire contents of the source diskette 

6) Before anything will be converted, you'll see 

DO YOU WANT PROMPTING? 
For now, type M for No* 

7) When you see 

INSERT DISKS THEN PRESS <ESC> TO RETURN TO 
MAIN MENU OR ANY OTHER KEY TO BEGIN 

remove the System Master diskette from the drive and Insert a 13 sector 
diskette containing files you wish to convert to 16 sector. Then press 
RETURN. 

8) After the message 

INSERT SOURCE DISK AND PRESS A KEY 
appears, simply press RETURN* 

9) The program will now find the first file on your 13 sector diskette 
and print its name. Then it will stop and wait for you to replace that 
diskette with a 16 sector <IN ITialf zed) diskette. Do this and press 
RETURN. 

You'll see 

DONE 

when the file has been converted. Then you'll he Instructed to re- insert 
the source diskette. Repeat this procedure until all your 13 sector 
files have been converted into 16 sector files. 

Note: To convert large files, you may need to swap diskettes several times 
for to get whole file transferred. 

When you are converting files ufling more thsn one disk drive, specify the 
slot and drive nuabers of the source and destination diskettes when the 
program asks for them (steps 3 and 4 above). Place the diakettes in the 
appropriate drives (step 8) before the conversion hefiins. 

When you see the message 

INSERT DISKS THEN PRESS <ESC> TO RETURN TO 
MAIN MENU OR ANY OTHER KEY TO BEGIN 

you have the chance to change your mind about converting the file. If you 
press ESC here, the program will stop in its tracks and send you back to 
the menu. 
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If you try to convert a 13 sector file with the sane name as a file 
already on the destination diskette* you'll see: 



PILE [filename] 

ALREADY EXISTS* 
TYPE IN A NEW FILE NAME FOR THE COPY 
OR < RETURN > TO REPLACE EXISTING PILE 
OR <CTRL-C><RETURN> TO CANCEL COPY: 

At this point you may either (a) type a new nan* for the file to be 
converted, (b) convert the 13 sector file and have It replace the file 
currently on the 16 sector destlnatioo under that name or (c) type CTRL-C 
and press RETURN to halt the conversion- 

USING WILDCARD CHARACTERS 

As you saw in the example. m may be used to mean "all files on the 

diskette". The * may also stand for any character or group of characters 

within a filename* For example. If you respond to the question 

FILENAME? 

by typing 

FI-LE 

you will convert all files on the 13 sector source diskette whose names 
begin with FI and cod with IE* In the same way, -TEXT converts all files 
whose names end with TEXT and all files with ns&es containing an *• 

Because the - acts like a wild card in a csrd game It's called the 
"wildcard character". 

The question 

DO TOU WANT PROMPTING? 

will appear when you use the wildcard character. If you respond with Y 
here, the program will stop after finding each file on the 13 sector 
diskette and wait for you to Indicate whether or not to convert chat file 

(by typing Y or N, or Q to stop and return to the isenu). A response of N 
to 

DO YOU WANT PROMPTING? 

indicates that all the files In the wildcard group should be converted. 
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to DOB 
to D05 



1M 




GENERAL INDEX 



Also see the PROGRAM INDEX and che MESSAGE INDEX at the end of this sect 

Inside the manual's back cover is the COMMAND SUMMARY INDEX and the 
PROCEDURE SUM1ARY INDEX. 



a: see A (address) parameter 

A-register 94-95 

A <address) parameter 92, 153 

with BLOAD 93 

with BRUN 93 
absolute byte parameter 69-70 

absolute-field position 

(R) parameter 79 
address field 94 
address (A) parameter 92, 150 
analog board schematics 146 
APPEND 66-6 7, 159 
Apple II BASIC Programming Manual 

10 

Applesoft BASIC 28-29 
Applesoft II BASIC Programming 

Reference Manual 10, 48 
Applesoft firmware ROM card 107 
APPLESOFT program 29 

-B- 

b: see B (byte) parameter 
B (byte) parameter 

with READ 69-71, 89, 150 
with WRITE 69-71, 89, 150 
backing up 37-38 

BASICS diskette 182 

binary files 92 

BLOAD 93, 163 

booting 11-12, 166 
13 sector 182 

BRUN 45, 93, 163 

BSAVE 92,163 

byte (B) paraMETER 6*-7i 



-C- 



C, control 18, 39 

C (command) parameter 
with HON 42 
with NOMON 42 

cable 2-4 

CALL -151 29 

CALL -868 43 



cassette tape recorder 15, 25 
CATALOG 16, 152 
CHAIN 106, 158 

chaining in Applesoft 106, 171 

CHRS(4) 30 

CLOSE 158, 161 

command (C) parameter 42 

control character 17, 30, 151 

controller card 2-4 

CONTACT 2 

COPY program 38-40 

COPYA program 38-40 

copying 

diskettes 38-40 
programs 15-16 

text files 134 
CTRL (control) 11, 148 
CTRL-C 18, 39 

CTRL-D 29- 31, 156-157, 166 
CTRL-K 103 
CTRL-P 103 



-D 



d: see D (drive) parameter 
D$ 30 

D, control 29-31, 156-157, 166 

D (drive) parameter 22, 149 

data field 94 

data files: see text files 

debugging 42 

default values 22 

deferred-execution mode 29-31, 48 

DELETE 18, 26, 154 

device characteristics table 

94-98 
disk(ette) 

care of 5-6 

CATALOG 16, 

directory of f 
129-131 

format 94 

IHITiallzing 

insertion and 

storage 124 

volume number 
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sector 



format 



13-14, 18, 166 
removal 6-7 

23 
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disk drive 
care 5 

installation 2-4 
multiple drives 5, 22 
t roubleshoot lng 12 
DISK FULL 120 

display options: see HON, NOMON 
DOS (Disk Operating System) 
command summary 110*111, 
148-164 

cemmands from within a program 
31. 166 

input, output registers 
101. 104 

memory usage 140 

messages 114-122 

procedure summary 165-171 
drive option: see drive parameter 
drive (D) parameter 22 
duplicating disks 38-40 

-I- 

END OF DATA 11? 

erasing files 18, 26, 154 

error codes 114*115 
error messages 114*122 

also see MESSAGE INDEX 
ESC (escape) 11, 149 
EXEC 74-79, 160-161 
EXEC files 75 

creating 75 

-F- 



— G— 

GET 51 

greeting program 13-14 
renaming 45 

-H- 



HELLO program 13 
hexadecimal notation 
HIMEH: 12, 141 
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-I- 



1/0 devlcea 100 

I/O ERROR 119 

I (Input) parameter 42 
Immediate-execution mode 31-48 

"IN USE" light 7, 18 
IN# H, 100-102, 157 

INIT (INITialUe) 13, 31, 151, 
166 

INPUT 51 

Input/Output control Block (IOB) 

94-98 
Input registers 

DOS 101, 104 

Monitor 101, 103 
Input (1) parameter 42 
Installing the DISK II 2-4 
INT 28-29, 156 
Integer BASIC 28-29 
Interface circuit schematics 145 



FID 184-189 
field 51, 124 

field (R) parameter 
with EXEC 79 

with POSITION 67-69 
file 16 

data: see text 
EXEC 74 

machine language 92-93 
names 16-17, 25, 151 
random-access text file 82-89 
sequential text file 49-71 
text file 48 

file buffer 43, 124 
FILE NOT FOUND 118 
FILE LOCKED 120 
FILE TYPE MISMATCH 121 
floating point BASIC: 

see Applesoft BASIC 
FP 28-29 



—J— 

J: see L (length) 
JMP (jusjp) 93 



pa 



ter 



-K- 

kick: see booting 



LANGUAGE NOT AVAILABLE 115 

L (length) parameter 
with BSAVE 92, 150 
with OPEN 88, 126, 150 

length (L) parameter 

of-binary-f lie 92 

of record 88, 126 
LOAD 16, 25-26, 153 
LOCK 35, 154 
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— R— 



machine-language files 92-93 

MAKE TEXT 61-64 

MASTER CREATE 44-46 

•aster diskettes 44-46 

HAXFILES 31, 43-44, 155-156 

memory requirements 13, 140 

memory usage and map 140 

MON 42-43, 155 

Monitor mode 50 

Monitor I/O registers 101, 103 

MUFFIN program 192-194 



NO BUFFERS AVAILABLE 121 
NOMON 42-43, 155 
NOT DIRECT COMMAND 122 
notation 148-150 

-o- 

(output) parameter 

with MON 42 

with NOMON 42 

ONERR GOTO 114 
OPEN 49-71, 158, 161 

output registers 
DOS 101, 104 
Monitor 101, 103 

overwriting 63-64, 69 



-P- 



R parameter 

with EXEC 79 

with POSITION 67-69, 125 

with READ 67-68, 150 

with WRITE 67-68, 150 
RUTS subroutine 94-98 
random-access text file 82-89 

creating and retrieving 82-85, 
170 

differences from sequential 82 

sample programs 82-87 
RANGE ERROR 116 
READ 

with ran dom-ac cess text files 

88-89, 137. 162 
with sequential text files 

49-71, 136 f 159 

read or write a track 
or sector 94-98 

record 82, 126 

record number (R) paraaeter 82-86 
relative-field position 

(R> parameter 67-69 
RENAME 17 , 153 
RESET 11, 18, 149, 166 
RETRIEVE TEXT 65-66 
RETURN 11, 12, 149 
RE1URN character 51 
ribbon cable 2-4 
RUN 25-26, 153 

-s- 



p: sea relative-field position 

(R) parameter 
P. control 103 
POSITION 66-68, 125, 159-160 
PR# 11, 100-102, 157 
PRINT (with CTRL-D) 29-31, 50 
PROGRAM TOO LARGE 29 

prompt characters 1 1 , 36 
PROMS 174-176 



quotation marks 30 



s: see S (slot) parameter 
S (slot) parameter 22, 149 
SAVE 15, 25-26, 152 
schematics 145-146 
sector 16, 94, 124 

allocation order 135 

13 to 16 conversion 192-194 

format 127-128 
sequential text file 49-71 

creating and retrieving 49-71, 
167-168 

EXEC 76, 169 

sample programs 49-71 
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= -4 

4 

&i -I 

? -1 

f? ■! 

E -a 

E -3 
E .< 

E 

E -4 
E^l 
E -I 
E i| 
E •< 
F -I 
■M 



slave diskettes 13, 141 
slots 3 

slot (S) parameter 22, 149 
syntax 148-150 
SYNTAX ERROR 120 

System Master diskette 10, 13-14 

-T- 

text file, random-access: 
see random-access text file 

text file, sequential: 
see sequential text file 

TRACE 44 

track allocation order 135 
track bit map 124, 133-134 
track/sector list 124, 128-129 
tracks 94, 124 

turnkey system 34-35, 167, 177 

-u- 

UNLOCK 35, 1 54 
unpacking 2 

-v- 

v: see V (volume) parameter 

V (volume) parameter 23, 149 

VERIFY 35-36, 154 

VOLUME MISMATCH 118-119 

volume number: see volume parameter 

volume (V) parameter 23, 149 

VTOC (volume table of contents) 

132-133 

-w- 

vildcard characters 184, 193 
WRITE 

with random-access text files 

88-89* 126» 162 
with sequential text files 

49-71. 124-125. 159 
write protecting 36—37 
WRITE PROTECTED 116 

-X-Y-Z- 

Y-register 94-95 
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DOS MESSAGE INDEX 



ERROR # 


MESSAGE 


9 


DISK FULL 


5 


END OF DATA 


19 


FILE LOCKED 


6 


FILE NOT FOUND 


L3 


PILE TYPE MISMATCH 


8 


I/O ERROR 


1 


LANGUAGE NOT AVAILABLE 


12 


NO BUFFERS AVAILABLE 


15 


NOT DIRECT COMMAND 


14 


PROGRAM TOO LARGE 


2,3 


RANGE ERROR 


11 


SYNTAX ERROR 


7 
4 


VOLUME MISMATCH 
WITE PROTECTED 



PAGES 

120 

53, 58, 67, 68, 70, 79, 86, 117- 
118, 160, 161 

35, 67, 120 

17, 18, 26, 36, 46, 59, 118, 154 
35, 48, 121, 152 

22, 26. 36, 119, 154 

28, 115, 153 
43, 121, 156 
48, 122 

29, 122 
92, 116 

10, 26, 28, 79, 92, 120 

23, 118-119 
37, 116-117 



PROGRAM INDEX 



PROGRAM 



PAGES 



Greeting (HELLO) 
COUNT 

CATALOG -Greeting 
COLOR DEMO 
ANIMALS 
COPY 

MASTER CREATE 
EXEC DEMO 
CAPTOR E 

RANDOM, APPLE PROMS 

CHAIN 
FID 

MUFFIN 



13-14 
15 

29-30 

34-35 
37 

38-40 
44-46 
74-75 
76-77 
86-88 

106-107 
184-189 
192-194 



200 





e 


-1 


E 


rl 


E 




s 


H 


E 


4 


E 


i 


e 


■A 


E 


•i 


E 


•1 


E 


•< 


E 
E 

E 
E 

E 


H 

■1 


E 

E 
E 
E 


SI 

=1 
•=1 
=1 



I 



DOS 

QUICK REFERENCE CARD 

On this card, DOS commands are grouped Into 
these 5 categories: 

Housekeeping commands: 

I NIT LOAD DELETE VERIFY HAXFILES 

CATALOG RUN LOCK HON 

SAVE RENAME UNLOCK NOMON 

Access Commands: 

IT INT PR# INI CHAIN 




EXEC 



CLOSE WRITE POSITION 

Random-Access Text File Commands: 

>UMN CLOSE READ WRITE 

Machine-Language File Commands_:_ 

BLOAD BRUTJ BSAVE 



NOTATION AND SYNTAX 

A "parameter" is a capital letter, usually 
followed by a number (shown here by a 
lower-case letter), which gives additional 
information for executing a command- 
Multiple parameters may appear in any 
order, but must be separated from each 
other by a comma* A parameter shown in 
square brackets [like this] is optional* 

A file name (shown here by X ) must immedi- 
ately follow its command word. File names 
must begin with a letter; only the first 
30 characters are used* A coma separates 
a file name from a following parameter. 

CTRL-D (type D while holding down CTRL key) 
is used in PRINT statements to Indicate the 
start of a deferred-execution DOS command- 
Integer BASIC example: 

10 DS - : REM "CTRL-D" 

20 PRINT DS; "CATALOG" 
Applesoft BASIC example: 

10 DS = CHRS(4) : REM CTRL-D 

20 PRINT DS; "CATALOG" 



The term "BASIC" alone is used to mean either 
Integer BASIC or Applesoft BASIC* The term 
"file" alone means an^ type of diskette file* 



COMMAND PARAMETERS 



HOUSEKEEPING COMMANDS 



An error message is given If a DOS command 
quantity is too large or too small. 



ALL FILES 



Par.-iist-NMi 
Slot 
Drive 
Volume 



As shown Min 



,Ss 
.Dd 
,Vv 



SI 

Dl 
V0 



Max 



S7 
D2 

V254 



* Using V0 is like omitting the Vv parameter: 
the diskette's volume number is ignored. 
Smallest volume number INIT will actually 
assign to a diskette is 1* 



SEQUENTIAL TEXT FILES 

As shown 



Byte 



,Bb 




Relative Field * ,Rp R0 

* With EXEC, always relative to field 0. 



B32767 
R32767 



INIT X l,Vv) USs] f.Dd] 

Initializes a blank diskette to form a slave 
diskette* Assigns greeting program name X 
and volume number v (If specified)* SAVEs 
the BASIC program currently in memory, under 
file name X . 



CATALOG USs) [,Dd) 

Displays volume number and all files on a 
diskette, with each file's type and sector 
length. * indicates a LOCKed f 11*. 



Description 



(How created) 



I 
A 
T 



Integer BASIC program file (SAVE) 
Applesoft BASIC program file (SAVE) 
Text File (OPEN, then WRITE) 

Binary memory-image file (BSAVE) 



SAVE X [ t Ss] l,DdJ [,VvJ 

Stores current BASIC program onto diskette, 
under file name X * Overwrites any previous 
file of same type and name, without warning. 



RAN DOM- ACCESS TEXT 


FILES 
As shown 


M i n 


Max 


Record Length 


.L| 


LI 


L32767 


Record Number 


,Rr 


R<* 


R32767 


BINARY FILES 








Parameter 


As shown 


Hin 


Max 



Starting Address ,Aa 
Number of Bytes ,LJ 



LI 



A32767 



LOAD X [,Ss) UDdJ LVv) 

Loads BASIC program file X Into memory, 
after clearing memory and (if necessary) 
changing to the correct BASIC. 



RUN X USs) [,Dd] UVvl 
LOADs BASIC program file 
then RUKs the program. 



RENAME X, Y USs) UDdJ [,Vvl 
Changes a diskette file's name from 



X to Y 



DOS COMMANDS 



Command 



As shown 



Min 



PR# 
IN# 

HAXFILES 



slot 
slot 
file buffers 



PR# i 

INI s 
HAXFILES 



IN#0 
n n-1 



PR#7 
1N#7 
n-16 



Commands use Slot or Drive parameters only 
when changing to a different Slot or Drive, 

If a command omits the Volume parameter or 
uses V0 , the diskette's volume number is 
ignored. A command that uses the Volume 
parameter Vv will not be executed unless 
Che diskette's volume number is v ■ 



DELETE X USs) UN] UVvl 
Erases file X from the diskette. 



LOCK X USs) UDd) UVvl 

Locks file X against accidental chmngs or 
deletion. LOCKed file shown In CATALOG by * 



UNLOCK X USs] UDd) |,Vv| 
Unlocks previously LOCKed f (U 
to allow change or deter ion. 



VERIFY X I.Sal t.Ddl LVv] 
Checks file X for internal consistency. 
Xf X was saved without error, no message 
Is given- 



HON (,C1 MJ [,0] 

Causes display of disk Commands ( C > t 
input from the disk < I ) t and Output 
to the disk < )- With no parameters, 
MON is ignored. 



KOMON [,C1 [,IJ [,OJ 

Cancels display of disk Commands ( C 
l^nput from the disk ( I ), and Output 
to the disk < ). With no parameters, 
NOMON is ignored. 



MAXFILES n 

Reserves n file buffers for disk input and 
output (booting reserves 3 file buffers). 
Use before LOADing or RUNning a program. 



ACCESS COMMANDS 

FP l,Ssl [ t Ddl |,Vv) 

Puts system into Applesoft BASIC, 

erasing any progran in memory. 

INT 

Puts system into Integer BASIC, 
erasing any program in memory. 

PRl s 

Sends subsequent output to slot s * Boots 
disk if slot s contains disk controller 
card. PRI0 sends output to TV screen again, 

INI s 

Takes subsequent input from slot s . Boots 
disk if slot s contains disk controller 
card. IN*0 takes input from keyboard again. 



CHAIN Y [,Ss] [,DdJ l,W] 

RUNs Integer BASIC program file Y , but does 
not clear variables developed by previous 
Integer BASIC program. 



SEQUENTIAL TEXT FILE COMMANDS 

OPEN X [,Ss] UDd) |,Vv] 

Opens or creates sequential text file X f 
allocates one file buffer and prepares to 
WRITE or READ from beginning of file. 

CLOSE [X) 

Completes WRITE X, if necessary, and de- 
allocates file buffer assigned to text file 

X . Without file name, CLOSES all OPEN files 

(except an EXEC file). 

WRITE X l,Bbl 

Subsequent PRINTs send characters to 
sequential text file X . WRITEing begins 
at current file position or (if specified) 
at byte b . Cancelled by any DOS command. 

READ X [,Bb| 

Subsequent INPUTs and GETs take response 
characters from sequential text file X . 
REAJJing begins at current file position or 
(if specified) at byte b . INPUT response 
is one field (all characters to next 
RETURH). Cancelled by any DOS command. 

APPEND X (,5s) MM) WVv] 
Opens existing sequential text file X , 
similar to OPEN, but prepares to WRITE 
at the end of the file. 

POSITION X, Rp 

In OPEN sequential text file X , subsequent 
READ or WRITE will proceed from p-th field 
following current file position. 

EXEC X |,Rp) [ t SsJ l.Ddl [,WJ 
Executes successive fields in sequential 
text file X as if typed at keyboard. 
With Rp p-irnmeter, execution begins with 
p-th field. Fields may include numbered 
BASH: program lines and direct-execution 
BASIC i*r DOS commands to control the Apple. 



RANDOM-ACCESS TEXT FILE 
COMMANDS 

OPEN X, Lj (,Ss) UDdl (,Vvl 

Opens or creates random-access text file X » 
allocates one file buffer, and defines record 
length as J bytes. Prepares to WRITE or READ 
from beginning of Record 0. Same Length param- 
eter must be used each time file X is OPENed - 



CLOSE IX] LSsl l,Dd) UW) 
Completes WRITE X, if necessary, and de- 
allocates file buffer assigned to text file 
X . Without file name, CLOSEs all OPEN files. 

WRITE X (,Rr] [»Bb] 

Subsequent PRINTs send characters to random- 
access text file X . With no parameters, 
WRITEing begins at current file position. 
With Rr parameter alone, WRITEing starts at 
byte of Record r . With Bb parameter, 
WRITE starts at byte b of current or spec- 
ified Record. Cancelled by any DOS command. 

READ X [,Rr] [,BbJ 

Subsequent INPUTS and GETs take response 
characters from random-access text file X < 
With no parameters, READing starts at cur- 
rent file position. With Rr parameter 
alone, READing starts at byte 9 of Record r. 
With Bb parameter, READing starts at byte 
b of current or specified Record. INPUT 
response is one field (all characters to 
next RETURN). Cancelled by any DOS command. 

MACHINE-LANGUAGE FILE 
COMMANDS 

BSAVE X, Aa> LJ [,Ss] UDdl (,Vv) 
Stores on diskette, under file name X > 
the contents of j memory bytes starting 
at address a * 

BLOAD X KAa] [,St] i,Dd) [,Vv] 
Loads binary file X into same memory 
locations from which file was BSAVEd or 
(if specified) starting at address a * 



ftRUN X (,Aa) (,Ss] (,Dd) [ f Vv] 

BLOADs binary file X , then jumps (JMP) 

to loaded file's first memory address. 
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